docs: update README with sprint 2 workflow details
This commit is contained in:
Joshua Magady
parent
e1c7043ba0
commit
9ac4540663
|
|
@ -11,9 +11,9 @@ The Technical Writing Expansion Pack extends BMad-Method with a comprehensive su
|
||||||
- 🤖 **6 Specialized Agents** - Complete writing team from planning to publication
|
- 🤖 **6 Specialized Agents** - Complete writing team from planning to publication
|
||||||
- 📝 **10 Core Tasks** - Full chapter development workflow
|
- 📝 **10 Core Tasks** - Full chapter development workflow
|
||||||
- 📋 **15 Quality Checklists** - Technical accuracy, security, performance, publisher compliance, accessibility
|
- 📋 **15 Quality Checklists** - Technical accuracy, security, performance, publisher compliance, accessibility
|
||||||
- 🎯 **9 Professional Templates** - Book planning, chapter development, review, and publishing
|
- 🎯 **10 Professional Templates** - Book planning, chapter development, section planning, review, and publishing
|
||||||
- 📚 **6 Knowledge Bases** - Comprehensive publisher guidelines and technical writing standards
|
- 📚 **6 Knowledge Bases** - Comprehensive publisher guidelines and technical writing standards
|
||||||
- 🔄 **5 Core Workflows** - Complete orchestration from book planning to technical review
|
- 🔄 **8 Core Workflows** - Section-driven development with complete orchestration from book planning to technical review
|
||||||
|
|
||||||
## ✍️ Included Agents
|
## ✍️ Included Agents
|
||||||
|
|
||||||
|
|
@ -61,16 +61,28 @@ npx bmad-method install
|
||||||
/bmad-tw:book-publisher
|
/bmad-tw:book-publisher
|
||||||
```
|
```
|
||||||
|
|
||||||
### Core Workflows (Sprint 2 & 2.5)
|
### Core Workflows (Sprint 2, 2.5, 2.6)
|
||||||
|
|
||||||
|
**Book Planning Workflow** _(Sprint 2.5)_ - Complete book planning from concept to approved outline:
|
||||||
|
|
||||||
**Book Planning Workflow** *(Sprint 2.5)* - Complete book planning from concept to approved outline:
|
|
||||||
1. Book Publisher drafts comprehensive book proposal
|
1. Book Publisher drafts comprehensive book proposal
|
||||||
2. Instructional Designer creates detailed book outline
|
2. Instructional Designer creates detailed book outline
|
||||||
3. Instructional Designer validates learning progression
|
3. Instructional Designer validates learning progression
|
||||||
4. Technical Editor reviews outline for clarity
|
4. Technical Editor reviews outline for clarity
|
||||||
5. Book Publisher verifies publisher requirements
|
5. Book Publisher verifies publisher requirements
|
||||||
|
|
||||||
**Chapter Development Workflow** *(Sprint 2)* - Complete chapter creation from outline to publisher-ready:
|
**Chapter Development Workflow v2.0** _(Sprint 2, refactored Sprint 2.6)_ - Complete chapter creation from outline to publisher-ready:
|
||||||
|
|
||||||
|
_Section-Driven Approach (NEW in v2.0):_
|
||||||
|
|
||||||
|
1. Tutorial Architect creates chapter outline
|
||||||
|
2. Tutorial Architect + Instructional Designer plan sections (section-planning-workflow)
|
||||||
|
3. For each section: Code Curator + Tutorial Architect + Technical Reviewer develop section (section-development-workflow)
|
||||||
|
4. Tutorial Architect + Technical Editor + Technical Reviewer assemble chapter (chapter-assembly-workflow)
|
||||||
|
5. Final validation and publication readiness
|
||||||
|
|
||||||
|
_Traditional Approach (Original, still supported):_
|
||||||
|
|
||||||
1. Tutorial Architect creates chapter outline
|
1. Tutorial Architect creates chapter outline
|
||||||
2. Code Curator develops and tests all code examples
|
2. Code Curator develops and tests all code examples
|
||||||
3. Tutorial Architect writes complete chapter draft
|
3. Tutorial Architect writes complete chapter draft
|
||||||
|
|
@ -79,7 +91,35 @@ npx bmad-method install
|
||||||
6. Technical Editor performs professional copy editing
|
6. Technical Editor performs professional copy editing
|
||||||
7. Tutorial Architect finalizes chapter for publication
|
7. Tutorial Architect finalizes chapter for publication
|
||||||
|
|
||||||
**Tutorial Creation Workflow** *(Sprint 2)* - Build effective hands-on tutorials:
|
**Section Planning Workflow** _(Sprint 2.6)_ - Break chapter into deliverable sections (BMad story analog):
|
||||||
|
|
||||||
|
1. Tutorial Architect analyzes chapter outline
|
||||||
|
2. Tutorial Architect identifies section boundaries (5-8 sections)
|
||||||
|
3. Tutorial Architect creates section plans with acceptance criteria
|
||||||
|
4. Instructional Designer validates learning flow
|
||||||
|
5. Tutorial Architect finalizes section list
|
||||||
|
|
||||||
|
**Section Development Workflow** _(Sprint 2.6)_ - Write one section (2-5 pages):
|
||||||
|
|
||||||
|
1. Code Curator develops section code examples
|
||||||
|
2. Code Curator tests all code
|
||||||
|
3. Tutorial Architect writes section content
|
||||||
|
4. Technical Reviewer performs focused section review
|
||||||
|
5. Tutorial Architect revises section
|
||||||
|
6. Tutorial Architect finalizes section (DONE)
|
||||||
|
|
||||||
|
**Chapter Assembly Workflow** _(Sprint 2.6)_ - Integrate completed sections (BMad Sprint Review analog):
|
||||||
|
|
||||||
|
1. Tutorial Architect merges all completed sections
|
||||||
|
2. Tutorial Architect improves transitions
|
||||||
|
3. Instructional Designer validates learning flow
|
||||||
|
4. Technical Reviewer performs full chapter review
|
||||||
|
5. Tutorial Architect revises based on feedback
|
||||||
|
6. Technical Editor performs copy editing
|
||||||
|
7. Tutorial Architect finalizes chapter for publication
|
||||||
|
|
||||||
|
**Tutorial Creation Workflow** _(Sprint 2)_ - Build effective hands-on tutorials:
|
||||||
|
|
||||||
1. Instructional Designer designs learning path
|
1. Instructional Designer designs learning path
|
||||||
2. Tutorial Architect creates step-by-step structure
|
2. Tutorial Architect creates step-by-step structure
|
||||||
3. Code Curator develops and tests tutorial code
|
3. Code Curator develops and tests tutorial code
|
||||||
|
|
@ -88,14 +128,16 @@ npx bmad-method install
|
||||||
6. Tutorial Architect revises based on testing
|
6. Tutorial Architect revises based on testing
|
||||||
7. Instructional Designer validates learning effectiveness
|
7. Instructional Designer validates learning effectiveness
|
||||||
|
|
||||||
**Code Example Workflow** *(Sprint 2.5)* - Develop, test, and document code examples:
|
**Code Example Workflow** _(Sprint 2.5)_ - Develop, test, and document code examples:
|
||||||
|
|
||||||
1. Code Curator develops code example
|
1. Code Curator develops code example
|
||||||
2. Code Curator tests on all target platforms
|
2. Code Curator tests on all target platforms
|
||||||
3. Code Curator verifies code quality
|
3. Code Curator verifies code quality
|
||||||
4. Code Curator performs security review
|
4. Code Curator performs security review
|
||||||
5. Code Curator adds comprehensive documentation
|
5. Code Curator adds comprehensive documentation
|
||||||
|
|
||||||
**Technical Review Workflow** *(Sprint 2.5)* - Comprehensive expert review of chapter:
|
**Technical Review Workflow** _(Sprint 2.5)_ - Comprehensive expert review of chapter:
|
||||||
|
|
||||||
1. Technical Reviewer verifies technical accuracy
|
1. Technical Reviewer verifies technical accuracy
|
||||||
2. Code Curator reviews all code examples
|
2. Code Curator reviews all code examples
|
||||||
3. Technical Reviewer validates best practices
|
3. Technical Reviewer validates best practices
|
||||||
|
|
@ -112,14 +154,16 @@ npx bmad-method install
|
||||||
|
|
||||||
## 📋 Key Components
|
## 📋 Key Components
|
||||||
|
|
||||||
### Templates (9 Total)
|
### Templates (10 Total)
|
||||||
|
|
||||||
**Sprint 1 (Planning):**
|
**Sprint 1 (Planning):**
|
||||||
|
|
||||||
- `book-outline-tmpl.yaml` - Complete book structure with learning path
|
- `book-outline-tmpl.yaml` - Complete book structure with learning path
|
||||||
- `chapter-outline-tmpl.yaml` - Individual chapter planning with exercises
|
- `chapter-outline-tmpl.yaml` - Individual chapter planning with exercises
|
||||||
- `code-example-tmpl.yaml` - Code examples with explanations and testing
|
- `code-example-tmpl.yaml` - Code examples with explanations and testing
|
||||||
|
|
||||||
**Sprint 2 (Writing & Publishing):**
|
**Sprint 2 (Writing & Publishing):**
|
||||||
|
|
||||||
- `chapter-draft-tmpl.yaml` - Complete chapter manuscript structure
|
- `chapter-draft-tmpl.yaml` - Complete chapter manuscript structure
|
||||||
- `technical-review-report-tmpl.yaml` - Review findings and recommendations
|
- `technical-review-report-tmpl.yaml` - Review findings and recommendations
|
||||||
- `tutorial-section-tmpl.yaml` - Step-by-step tutorial structure
|
- `tutorial-section-tmpl.yaml` - Step-by-step tutorial structure
|
||||||
|
|
@ -127,9 +171,14 @@ npx bmad-method install
|
||||||
- `book-proposal-tmpl.yaml` - Publisher proposal document
|
- `book-proposal-tmpl.yaml` - Publisher proposal document
|
||||||
- `introduction-tmpl.yaml` - Chapter introduction structure
|
- `introduction-tmpl.yaml` - Chapter introduction structure
|
||||||
|
|
||||||
|
**Sprint 2.6 (Section-Driven Development):**
|
||||||
|
|
||||||
|
- `section-plan-tmpl.yaml` - Section plan with acceptance criteria (BMad story analog)
|
||||||
|
|
||||||
### Tasks (10 Total)
|
### Tasks (10 Total)
|
||||||
|
|
||||||
**Sprint 1 (Planning):**
|
**Sprint 1 (Planning):**
|
||||||
|
|
||||||
- `design-book-outline.md` - Create publisher-aligned book structures
|
- `design-book-outline.md` - Create publisher-aligned book structures
|
||||||
- `create-code-example.md` - Develop tested, documented code examples
|
- `create-code-example.md` - Develop tested, documented code examples
|
||||||
- `test-code-examples.md` - Automated testing workflow for all examples
|
- `test-code-examples.md` - Automated testing workflow for all examples
|
||||||
|
|
@ -137,6 +186,7 @@ npx bmad-method install
|
||||||
- `create-chapter-outline.md` - Plan chapter structure and content
|
- `create-chapter-outline.md` - Plan chapter structure and content
|
||||||
|
|
||||||
**Sprint 2 (Writing & Review):**
|
**Sprint 2 (Writing & Review):**
|
||||||
|
|
||||||
- `write-chapter-draft.md` - Complete chapter manuscript writing workflow
|
- `write-chapter-draft.md` - Complete chapter manuscript writing workflow
|
||||||
- `technical-review-chapter.md` - Comprehensive chapter review workflow
|
- `technical-review-chapter.md` - Comprehensive chapter review workflow
|
||||||
- `copy-edit-chapter.md` - Editorial polish workflow
|
- `copy-edit-chapter.md` - Editorial polish workflow
|
||||||
|
|
@ -146,6 +196,7 @@ npx bmad-method install
|
||||||
### Checklists (15 Total)
|
### Checklists (15 Total)
|
||||||
|
|
||||||
**Sprint 1 (Quality Foundations):**
|
**Sprint 1 (Quality Foundations):**
|
||||||
|
|
||||||
- Learning objectives validation
|
- Learning objectives validation
|
||||||
- Code quality verification
|
- Code quality verification
|
||||||
- Code testing requirements
|
- Code testing requirements
|
||||||
|
|
@ -156,6 +207,7 @@ npx bmad-method install
|
||||||
- Version compatibility
|
- Version compatibility
|
||||||
|
|
||||||
**Sprint 2 (Review & Publishing):**
|
**Sprint 2 (Review & Publishing):**
|
||||||
|
|
||||||
- Technical accuracy checklist
|
- Technical accuracy checklist
|
||||||
- Security best practices checklist
|
- Security best practices checklist
|
||||||
- Performance considerations checklist
|
- Performance considerations checklist
|
||||||
|
|
@ -164,17 +216,25 @@ npx bmad-method install
|
||||||
- Manning MEAP checklist
|
- Manning MEAP checklist
|
||||||
- Accessibility checklist
|
- Accessibility checklist
|
||||||
|
|
||||||
### Workflows (5 Core Workflows)
|
### Workflows (8 Core Workflows)
|
||||||
|
|
||||||
**Sprint 2:**
|
**Sprint 2:**
|
||||||
- `chapter-development-workflow.yaml` - Complete chapter creation workflow
|
|
||||||
|
- `chapter-development-workflow.yaml` - Complete chapter creation workflow (v2.0 - refactored Sprint 2.6)
|
||||||
- `tutorial-creation-workflow.yaml` - Tutorial development workflow
|
- `tutorial-creation-workflow.yaml` - Tutorial development workflow
|
||||||
|
|
||||||
**Sprint 2.5:**
|
**Sprint 2.5:**
|
||||||
|
|
||||||
- `book-planning-workflow.yaml` - Book planning from concept to approved outline
|
- `book-planning-workflow.yaml` - Book planning from concept to approved outline
|
||||||
- `code-example-workflow.yaml` - Code example development and testing
|
- `code-example-workflow.yaml` - Code example development and testing
|
||||||
- `technical-review-workflow.yaml` - Comprehensive technical review
|
- `technical-review-workflow.yaml` - Comprehensive technical review
|
||||||
|
|
||||||
|
**Sprint 2.6 (Section-Driven Development):**
|
||||||
|
|
||||||
|
- `section-planning-workflow.yaml` - Break chapter into sections (BMad epic → stories analog)
|
||||||
|
- `section-development-workflow.yaml` - Write one section (BMad story development analog)
|
||||||
|
- `chapter-assembly-workflow.yaml` - Merge sections into chapter (BMad sprint review analog)
|
||||||
|
|
||||||
### Knowledge Bases (6 Total)
|
### Knowledge Bases (6 Total)
|
||||||
|
|
||||||
- `bmad-kb.md` - Core technical writing methodology
|
- `bmad-kb.md` - Core technical writing methodology
|
||||||
|
|
@ -235,13 +295,14 @@ Special thanks to Brian (BMad) for creating the BMad Method framework.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**Version:** 0.2.5 (Sprint 2.5 - Workflow Completion)
|
**Version:** 0.2.6 (Sprint 2.6 - Section-Driven Development)
|
||||||
**Compatible with:** BMad Method v4.0+
|
**Compatible with:** BMad Method v4.0+
|
||||||
**Last Updated:** 2024
|
**Last Updated:** 2024
|
||||||
|
|
||||||
## ✅ Sprint Status
|
## ✅ Sprint Status
|
||||||
|
|
||||||
**Sprint 1 (Complete):** Planning and design foundation
|
**Sprint 1 (Complete):** Planning and design foundation
|
||||||
|
|
||||||
- ✅ 3 planning agents (Instructional Designer, Tutorial Architect, Code Curator)
|
- ✅ 3 planning agents (Instructional Designer, Tutorial Architect, Code Curator)
|
||||||
- ✅ 5 core tasks for book and chapter planning
|
- ✅ 5 core tasks for book and chapter planning
|
||||||
- ✅ 8 quality checklists
|
- ✅ 8 quality checklists
|
||||||
|
|
@ -249,6 +310,7 @@ Special thanks to Brian (BMad) for creating the BMad Method framework.
|
||||||
- ✅ 6 knowledge bases (initial versions)
|
- ✅ 6 knowledge bases (initial versions)
|
||||||
|
|
||||||
**Sprint 2 (Complete):** Review, workflows, and quality assurance
|
**Sprint 2 (Complete):** Review, workflows, and quality assurance
|
||||||
|
|
||||||
- ✅ 3 review agents (Technical Reviewer, Technical Editor, Book Publisher)
|
- ✅ 3 review agents (Technical Reviewer, Technical Editor, Book Publisher)
|
||||||
- ✅ 5 additional tasks for writing and review
|
- ✅ 5 additional tasks for writing and review
|
||||||
- ✅ 7 additional checklists (technical, security, performance, publisher, accessibility)
|
- ✅ 7 additional checklists (technical, security, performance, publisher, accessibility)
|
||||||
|
|
@ -257,13 +319,72 @@ Special thanks to Brian (BMad) for creating the BMad Method framework.
|
||||||
- ✅ Expanded knowledge bases (publisher guidelines, writing standards)
|
- ✅ Expanded knowledge bases (publisher guidelines, writing standards)
|
||||||
|
|
||||||
**Sprint 2.5 (Complete):** Workflow orchestration completion
|
**Sprint 2.5 (Complete):** Workflow orchestration completion
|
||||||
|
|
||||||
- ✅ 3 additional workflows: Book Planning Workflow, Code Example Workflow, Technical Review Workflow
|
- ✅ 3 additional workflows: Book Planning Workflow, Code Example Workflow, Technical Review Workflow
|
||||||
- ✅ Total: 5 core workflows for complete book development
|
- ✅ Total: 5 core workflows for complete book development
|
||||||
- ✅ Version bumped to 0.2.5
|
- ✅ Version bumped to 0.2.5
|
||||||
|
|
||||||
|
**Sprint 2.6 (Complete):** Section-driven development (BMad story analog)
|
||||||
|
|
||||||
|
- ✅ 3 section-level workflows: Section Planning, Section Development, Chapter Assembly
|
||||||
|
- ✅ 1 new template: Section Plan Template (section acceptance criteria)
|
||||||
|
- ✅ Refactored Chapter Development Workflow v2.0 (orchestrates section workflows)
|
||||||
|
- ✅ Total: 8 core workflows, 10 templates
|
||||||
|
- ✅ Section-driven approach enables incremental chapter writing (2-5 pages per section)
|
||||||
|
- ✅ Perfect analog to BMad's story-driven development workflow
|
||||||
|
- ✅ Parallel section development supported
|
||||||
|
- ✅ Backward compatible: Traditional full-chapter approach still supported
|
||||||
|
- ✅ Version bumped to 0.2.6
|
||||||
|
|
||||||
|
## 📚 Section-Driven Development Approach (NEW in Sprint 2.6)
|
||||||
|
|
||||||
|
The section-driven approach mirrors BMad's story-driven development workflow, enabling incremental chapter writing:
|
||||||
|
|
||||||
|
**Key Concepts:**
|
||||||
|
|
||||||
|
- **Section = Story analog**: Each section is a 2-5 page deliverable unit with clear acceptance criteria
|
||||||
|
- **Incremental progress**: Track "Chapter 3: 5 of 8 sections complete" like story completion
|
||||||
|
- **Parallel development**: Multiple sections can be developed simultaneously if dependencies allow
|
||||||
|
- **Work-in-progress reviews**: Review sections as they're completed, not waiting for full chapter
|
||||||
|
- **Story-driven iteration**: Write → Review → Polish cycle at section level
|
||||||
|
|
||||||
|
**Typical Chapter Breakdown:**
|
||||||
|
|
||||||
|
- 20-page chapter = 5-8 sections
|
||||||
|
- Small section: 2-3 pages, 1 concept, 1 code example (3 story points)
|
||||||
|
- Medium section: 3-4 pages, 1-2 concepts, 2 code examples (5 story points)
|
||||||
|
- Large section: 4-5 pages, 2-3 concepts, 2-3 code examples (8 story points)
|
||||||
|
|
||||||
|
**Workflow Mapping:**
|
||||||
|
|
||||||
|
| BMad Software Dev | Book Writing (Section-Driven) |
|
||||||
|
| ----------------- | ------------------------------------------------ |
|
||||||
|
| PRD Creation | book-planning-workflow → book outline |
|
||||||
|
| Architecture | chapter-planning → chapter outline |
|
||||||
|
| Epic Breakdown | section-planning-workflow → section list |
|
||||||
|
| Story Development | section-development-workflow → completed section |
|
||||||
|
| Sprint Review | chapter-assembly-workflow → integrated chapter |
|
||||||
|
| Release | publisher-submission → published chapter |
|
||||||
|
|
||||||
|
**When to Use Section-Driven:**
|
||||||
|
|
||||||
|
- Chapters 15+ pages (too large for single sitting)
|
||||||
|
- Want incremental progress tracking
|
||||||
|
- Need parallel development capability
|
||||||
|
- Prefer iterative story-driven approach
|
||||||
|
- Want to review work before full chapter complete
|
||||||
|
|
||||||
|
**When to Use Traditional:**
|
||||||
|
|
||||||
|
- Short chapters (<10-12 pages)
|
||||||
|
- Simple reference sections
|
||||||
|
- Author prefers writing full chapter at once
|
||||||
|
- Chapter already partially written
|
||||||
|
|
||||||
## 🚧 Roadmap
|
## 🚧 Roadmap
|
||||||
|
|
||||||
**Sprint 3** (Planned):
|
**Sprint 3** (Planned):
|
||||||
|
|
||||||
- API Documenter agent
|
- API Documenter agent
|
||||||
- Screenshot Specialist agent
|
- Screenshot Specialist agent
|
||||||
- Additional publisher-specific agents
|
- Additional publisher-specific agents
|
||||||
|
|
|
||||||
|
|
@ -1,15 +1,17 @@
|
||||||
# <!-- Powered by BMAD™ Core -->
|
# <!-- Powered by BMAD™ Core -->
|
||||||
name: bmad-technical-writing
|
name: bmad-technical-writing
|
||||||
version: 0.2.5
|
version: 0.2.6
|
||||||
short-title: Technical Book Writing Studio
|
short-title: Technical Book Writing Studio
|
||||||
description: >-
|
description: >-
|
||||||
Comprehensive AI-powered technical writing framework for technical book
|
Comprehensive AI-powered technical writing framework for technical book
|
||||||
authors, technical trainers, and documentation specialists. Provides 6
|
authors, technical trainers, and documentation specialists. Provides 6
|
||||||
specialized agents, 5 core workflows, and professional quality assurance tools
|
specialized agents, 8 core workflows with section-driven development (BMad story
|
||||||
for planning, writing, reviewing, and publishing technical books with code
|
analog), and professional quality assurance tools for planning, writing,
|
||||||
examples, tutorials, and learning objectives. Includes 15 checklists for
|
reviewing, and publishing technical books with code examples, tutorials, and
|
||||||
technical accuracy, security, performance, publisher compliance, and
|
learning objectives. Includes 15 checklists for technical accuracy, security,
|
||||||
accessibility. Supports publishers like PacktPub, O'Reilly, Manning, and
|
performance, publisher compliance, and accessibility. Section-driven workflows
|
||||||
self-publishing platforms.
|
enable incremental chapter development (2-5 pages per section) with parallel
|
||||||
|
development capabilities. Supports publishers like PacktPub, O'Reilly, Manning,
|
||||||
|
and self-publishing platforms.
|
||||||
author: Wes
|
author: Wes
|
||||||
slashPrefix: bmad-tw
|
slashPrefix: bmad-tw
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,106 @@
|
||||||
|
# <!-- Powered by BMAD™ Core -->
|
||||||
|
---
|
||||||
|
template:
|
||||||
|
id: section-plan
|
||||||
|
name: Section Plan
|
||||||
|
version: 1.0
|
||||||
|
description: Detailed section plan defining acceptance criteria for one deliverable section (BMad story analog). Section is 2-5 pages with 1-2 learning objectives and clear success criteria.
|
||||||
|
output:
|
||||||
|
format: markdown
|
||||||
|
filename: "section-{{section_number}}.md"
|
||||||
|
|
||||||
|
workflow:
|
||||||
|
elicitation: false
|
||||||
|
allow_skip: false
|
||||||
|
sections:
|
||||||
|
- id: metadata
|
||||||
|
title: Section Metadata
|
||||||
|
instruction: |
|
||||||
|
Basic information:
|
||||||
|
- Section ID (e.g., "section-3.2" for chapter 3, section 2)
|
||||||
|
- Section title (descriptive, clear)
|
||||||
|
- Chapter number and chapter title
|
||||||
|
- Position in chapter (e.g., "2 of 8")
|
||||||
|
- Estimated pages (2-5 pages typical)
|
||||||
|
- Story points equivalent (Small=3, Medium=5, Large=8)
|
||||||
|
- id: learning_objective
|
||||||
|
title: Learning Objective
|
||||||
|
instruction: |
|
||||||
|
What this section teaches (1-2 objectives max):
|
||||||
|
- Use action verbs from Bloom's Taxonomy (implement, explain, demonstrate, apply)
|
||||||
|
- Be specific and measurable
|
||||||
|
- Focus on single concept or skill
|
||||||
|
- Examples:
|
||||||
|
* "Implement basic list operations in Python"
|
||||||
|
* "Explain memory management in dictionary structures"
|
||||||
|
* "Demonstrate error handling in file operations"
|
||||||
|
|
||||||
|
Keep focused - if you have 3+ objectives, section is too large.
|
||||||
|
- id: prerequisites
|
||||||
|
title: Prerequisites
|
||||||
|
instruction: |
|
||||||
|
What reader needs before this section:
|
||||||
|
- Previous sections that must be completed (by section ID)
|
||||||
|
- Concepts from earlier chapters assumed
|
||||||
|
- Code from previous sections that will be extended
|
||||||
|
- Tools or setup required (if new to this section)
|
||||||
|
- id: content_plan
|
||||||
|
title: Content Plan
|
||||||
|
instruction: |
|
||||||
|
Concepts to explain in this section:
|
||||||
|
- Main concept/topic (1-2 paragraphs description)
|
||||||
|
- Key points to cover (bullet list, 3-5 points)
|
||||||
|
- Theory/background needed (minimal, just enough)
|
||||||
|
- Tutorial approach (step-by-step? example-driven? problem-solving?)
|
||||||
|
- Estimated breakdown:
|
||||||
|
* Concept explanation: X pages
|
||||||
|
* Tutorial/walkthrough: X pages
|
||||||
|
* Practice/exercises: X pages
|
||||||
|
- id: code_examples
|
||||||
|
title: Code Examples Needed
|
||||||
|
instruction: |
|
||||||
|
Code examples for this section:
|
||||||
|
- Example 1: [filename] - [purpose] - [complexity: simple/medium/complex]
|
||||||
|
- Example 2: [filename] - [purpose] - [complexity]
|
||||||
|
- (continue as needed, typically 1-3 examples per section)
|
||||||
|
|
||||||
|
For each example specify:
|
||||||
|
- What it demonstrates
|
||||||
|
- Input and expected output
|
||||||
|
- Testing approach
|
||||||
|
- Common mistakes to highlight
|
||||||
|
- id: success_criteria
|
||||||
|
title: Success Criteria
|
||||||
|
instruction: |
|
||||||
|
This section is "DONE" when:
|
||||||
|
- [ ] Learning objective(s) clearly explained
|
||||||
|
- [ ] All code examples developed and tested
|
||||||
|
- [ ] Tutorial walkthrough complete with explanations
|
||||||
|
- [ ] Common mistakes and troubleshooting covered
|
||||||
|
- [ ] Section length 2-5 pages (not too short, not too long)
|
||||||
|
- [ ] Transitions to next section clear
|
||||||
|
- [ ] Technical reviewer approved section accuracy
|
||||||
|
- [ ] No outstanding technical issues
|
||||||
|
|
||||||
|
Add section-specific criteria as needed (e.g., "Performance example runs in <100ms")
|
||||||
|
- id: dependencies
|
||||||
|
title: Dependencies
|
||||||
|
instruction: |
|
||||||
|
Dependencies on other sections:
|
||||||
|
- Must complete before starting: [list section IDs]
|
||||||
|
- Can develop in parallel with: [list section IDs]
|
||||||
|
- Blocks these sections: [list section IDs that need this one]
|
||||||
|
|
||||||
|
Example:
|
||||||
|
- Must complete: section-3.1 (introduces list basics)
|
||||||
|
- Can parallel: section-3.4 (different topic)
|
||||||
|
- Blocks: section-3.3 (extends this section's code)
|
||||||
|
- id: notes
|
||||||
|
title: Development Notes
|
||||||
|
instruction: |
|
||||||
|
Additional guidance for section development:
|
||||||
|
- Key resources or references
|
||||||
|
- Known complexity areas
|
||||||
|
- Reader perspective considerations
|
||||||
|
- Connection to real-world use cases
|
||||||
|
- Special attention areas (security, performance, etc.)
|
||||||
|
|
@ -0,0 +1,178 @@
|
||||||
|
workflow:
|
||||||
|
id: chapter-assembly-workflow
|
||||||
|
name: Assemble and Polish Chapter
|
||||||
|
description: Integrate all completed sections into cohesive chapter (BMad Sprint Review analog). Merges sections, improves transitions, validates learning flow, performs full technical review, and finalizes chapter for publication.
|
||||||
|
type: chapter-integration
|
||||||
|
project_types:
|
||||||
|
- technical-book
|
||||||
|
- tutorial-series
|
||||||
|
- training-materials
|
||||||
|
- technical-documentation
|
||||||
|
sequence:
|
||||||
|
- agent: tutorial-architect
|
||||||
|
creates: chapter-integrated.md
|
||||||
|
requires: completed-sections[]
|
||||||
|
notes: "Merge all completed sections into single chapter file. Preserve section content. Add chapter introduction (if not in section 1) and chapter summary (if not in final section). Verify all sections present in correct order. SAVE OUTPUT: Create docs/chapters/chapter-{{chapter_number}}-integrated.md"
|
||||||
|
|
||||||
|
- agent: tutorial-architect
|
||||||
|
improves: chapter-integrated.md
|
||||||
|
requires: chapter-integrated.md
|
||||||
|
notes: "Review and improve transitions between sections. Add bridging paragraphs where sections feel disconnected. Ensure smooth flow from one concept to next. Check that prerequisites mentioned in earlier sections are fulfilled. Add cross-references where helpful. SAVE OUTPUT: Update chapter-integrated.md with improved transitions."
|
||||||
|
|
||||||
|
- agent: instructional-designer
|
||||||
|
validates: chapter-integrated.md
|
||||||
|
requires: chapter-integrated.md
|
||||||
|
notes: "Validate overall learning progression. Verify chapter builds concepts logically. Check that exercises progress from easy to challenging. Ensure no learning gaps or concept jumps. Confirm chapter learning objectives (from chapter outline) are achieved. SAVE OUTPUT: Create learning-flow-validation.md with findings."
|
||||||
|
|
||||||
|
- agent: technical-reviewer
|
||||||
|
reviews: chapter-integrated.md
|
||||||
|
requires: chapter-integrated.md
|
||||||
|
notes: "Perform comprehensive technical review of full chapter using *review-chapter command. Verify technical accuracy across all sections, test all code examples in sequence, check security best practices, assess performance implications. Use technical-accuracy-checklist, security-best-practices-checklist, and performance-considerations-checklist. SAVE OUTPUT: Create reviews/technical-review-chapter-{{chapter_number}}.md using technical-review-report-tmpl."
|
||||||
|
|
||||||
|
- agent: tutorial-architect
|
||||||
|
revises: chapter-integrated.md
|
||||||
|
requires:
|
||||||
|
- learning-flow-validation.md
|
||||||
|
- technical-review-report.md
|
||||||
|
notes: "Incorporate all review feedback. Address instructional designer learning flow issues. Fix all critical and major technical issues from technical review. Update code examples if needed. Re-test modified code. SAVE OUTPUT: Update chapter-integrated.md with all revisions."
|
||||||
|
|
||||||
|
- agent: technical-editor
|
||||||
|
edits: chapter-integrated.md
|
||||||
|
requires: revised-chapter-integrated.md
|
||||||
|
notes: "Perform professional copy edit using *edit-chapter command. Improve clarity, check terminology consistency, enhance transitions, verify publisher style compliance, review accessibility. Use accessibility-checklist and publisher-specific checklist. SAVE OUTPUT: Create edited-chapter.md with change summary."
|
||||||
|
|
||||||
|
- agent: tutorial-architect
|
||||||
|
finalizes: chapter-final.md
|
||||||
|
requires:
|
||||||
|
- edited-chapter.md
|
||||||
|
- chapter-completeness-checklist.md
|
||||||
|
notes: "Review and approve editorial changes. Verify technical accuracy preserved during editing. Run chapter-completeness-checklist to ensure all requirements met. Mark chapter status as 'Ready for Publication'. SAVE OUTPUT: Create docs/chapters/chapter-{{chapter_number}}-final.md as publisher-ready manuscript."
|
||||||
|
|
||||||
|
flow_diagram: |
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
A[Start: All Sections DONE] --> B[tutorial-architect: Merge Sections]
|
||||||
|
B --> C[tutorial-architect: Improve Transitions]
|
||||||
|
C --> D[instructional-designer: Validate Learning Flow]
|
||||||
|
D --> E[technical-reviewer: Full Chapter Review]
|
||||||
|
E --> F{Critical Issues?}
|
||||||
|
F -->|Yes| G[tutorial-architect: Revise Chapter]
|
||||||
|
G --> H[Update Code if Needed?]
|
||||||
|
H -->|Yes| I[Retest Code]
|
||||||
|
I --> E
|
||||||
|
H -->|No| E
|
||||||
|
F -->|No| J[technical-editor: Copy Edit]
|
||||||
|
J --> K[tutorial-architect: Review Edits]
|
||||||
|
K --> L{Approve Edits?}
|
||||||
|
L -->|No| M[Discuss with Editor]
|
||||||
|
M --> J
|
||||||
|
L -->|Yes| N[tutorial-architect: Run Completeness Checklist]
|
||||||
|
N --> O{All Criteria Met?}
|
||||||
|
O -->|No| P[Address Missing Items]
|
||||||
|
P --> N
|
||||||
|
O -->|Yes| Q[Chapter Ready for Publication]
|
||||||
|
|
||||||
|
B -.-> B1[Preserve section content]
|
||||||
|
C -.-> C1[Add bridging paragraphs]
|
||||||
|
D -.-> D1[Check learning progression]
|
||||||
|
E -.-> E1[Test all code in sequence]
|
||||||
|
J -.-> J1[Maintain author voice]
|
||||||
|
N -.-> N1[chapter-completeness-checklist]
|
||||||
|
|
||||||
|
style Q fill:#90EE90
|
||||||
|
style B fill:#FFE4B5
|
||||||
|
style C fill:#FFE4B5
|
||||||
|
style D fill:#ADD8E6
|
||||||
|
style E fill:#ADD8E6
|
||||||
|
style J fill:#ADD8E6
|
||||||
|
style N fill:#F0E68C
|
||||||
|
```
|
||||||
|
|
||||||
|
decision_guidance:
|
||||||
|
when_to_use:
|
||||||
|
- All chapter sections marked DONE
|
||||||
|
- Using section-driven development approach
|
||||||
|
- Ready to integrate sections into cohesive chapter
|
||||||
|
- Need full chapter review and polish
|
||||||
|
- Preparing chapter for publication
|
||||||
|
|
||||||
|
when_not_to_use:
|
||||||
|
- Sections still in development (wait until all DONE)
|
||||||
|
- Chapter written as single unit (already integrated)
|
||||||
|
- Quick draft without full review process
|
||||||
|
|
||||||
|
quality_gates:
|
||||||
|
integration_complete:
|
||||||
|
- All sections merged in correct order
|
||||||
|
- Chapter introduction present
|
||||||
|
- Chapter summary present
|
||||||
|
- No missing sections
|
||||||
|
- Section boundaries clear
|
||||||
|
|
||||||
|
transitions_complete:
|
||||||
|
- Smooth flow between sections
|
||||||
|
- No jarring concept jumps
|
||||||
|
- Cross-references added where helpful
|
||||||
|
- Bridging paragraphs where needed
|
||||||
|
- Reader guidance clear
|
||||||
|
|
||||||
|
learning_flow_validated:
|
||||||
|
- Concepts build logically
|
||||||
|
- Prerequisites met in order
|
||||||
|
- No learning gaps
|
||||||
|
- Exercises progress appropriately
|
||||||
|
- Chapter objectives achieved
|
||||||
|
- Checklist: instructional-designer validation
|
||||||
|
|
||||||
|
technical_review_passed:
|
||||||
|
- No critical technical errors
|
||||||
|
- All code tested in sequence
|
||||||
|
- Security best practices followed
|
||||||
|
- Performance considerations addressed
|
||||||
|
- No outdated information
|
||||||
|
- Checklists: technical-accuracy, security-best-practices, performance-considerations
|
||||||
|
|
||||||
|
editorial_complete:
|
||||||
|
- Grammar and spelling clean
|
||||||
|
- Terminology consistent throughout
|
||||||
|
- Publisher style followed
|
||||||
|
- Accessibility requirements met
|
||||||
|
- Author voice maintained
|
||||||
|
- Checklists: accessibility-checklist, publisher-specific
|
||||||
|
|
||||||
|
chapter_complete:
|
||||||
|
- All quality gates passed
|
||||||
|
- chapter-completeness-checklist verified
|
||||||
|
- Ready for publication
|
||||||
|
- All review feedback addressed
|
||||||
|
|
||||||
|
handoff_prompts:
|
||||||
|
sections_to_architect: "All {{section_count}} sections DONE. Total content: ~{{page_count}} pages. Ready to merge and assemble chapter."
|
||||||
|
merge_to_transitions: "Chapter sections merged. {{section_count}} sections integrated. Review transitions between sections for smooth flow."
|
||||||
|
transitions_to_designer: "Transitions improved. Chapter flows from {{first_section}} to {{last_section}}. Please validate learning progression."
|
||||||
|
designer_to_reviewer: "Learning flow validated. Chapter builds concepts logically with no gaps. Ready for comprehensive technical review."
|
||||||
|
reviewer_to_architect: "Technical review complete. Found {{critical_count}} critical, {{major_count}} major, {{minor_count}} minor issues. Full report at reviews/technical-review-chapter-{{chapter_number}}.md"
|
||||||
|
revised_to_editor: "All review feedback addressed. Chapter revised and code re-tested. Ready for copy editing."
|
||||||
|
editor_to_architect: "Copy editing complete. Improved clarity, consistency, and style while maintaining your voice. Change summary attached for approval."
|
||||||
|
architect_final: "Chapter {{chapter_number}} FINAL. All reviews passed, completeness checklist verified. {{page_count}} pages publisher-ready. Status: Ready for Publication."
|
||||||
|
|
||||||
|
time_estimates:
|
||||||
|
merge_sections: "1-2 hours"
|
||||||
|
improve_transitions: "2-3 hours"
|
||||||
|
validate_learning_flow: "1-2 hours"
|
||||||
|
technical_review: "3-5 hours (full chapter)"
|
||||||
|
revise_chapter: "3-6 hours (depending on issues)"
|
||||||
|
copy_edit: "2-4 hours"
|
||||||
|
finalize_chapter: "1-2 hours"
|
||||||
|
total_time: "13-24 hours per chapter"
|
||||||
|
|
||||||
|
best_practices:
|
||||||
|
- Wait until ALL sections DONE before assembly
|
||||||
|
- Preserve section content - don't rewrite during merge
|
||||||
|
- Focus on transitions and flow, not content changes
|
||||||
|
- Test all code examples in sequence (order matters)
|
||||||
|
- Address critical issues before copy editing
|
||||||
|
- Maintain author voice during editorial polish
|
||||||
|
- Use completeness checklist as final gate
|
||||||
|
- Chapter assembly is Sprint Review - celebrate progress
|
||||||
|
- All sections done = major milestone achieved
|
||||||
|
|
@ -1,8 +1,9 @@
|
||||||
workflow:
|
workflow:
|
||||||
id: chapter-development-workflow
|
id: chapter-development-workflow
|
||||||
name: Write and Refine Chapter
|
name: Write and Refine Chapter
|
||||||
description: Complete chapter creation workflow from outline to publisher-ready manuscript. Guides technical authors through planning, drafting, code development, technical review, and editorial polish. Emphasizes learning objectives, hands-on tutorials, tested code examples, and professional quality standards.
|
description: Complete chapter creation workflow from outline to publisher-ready manuscript. v2.0 - Orchestrates section-driven development (section-planning → section-development → chapter-assembly). Can also be used for traditional full-chapter writing. Emphasizes learning objectives, hands-on tutorials, tested code examples, and professional quality standards.
|
||||||
type: chapter-writing
|
type: chapter-writing
|
||||||
|
version: 2.0
|
||||||
project_types:
|
project_types:
|
||||||
- technical-book
|
- technical-book
|
||||||
- tutorial-series
|
- tutorial-series
|
||||||
|
|
@ -14,73 +15,81 @@ workflow:
|
||||||
requires: book-outline.md
|
requires: book-outline.md
|
||||||
notes: "Create detailed chapter outline using *create-chapter-outline command. Define learning objectives, prerequisites, main sections, exercises, and code examples needed. SAVE OUTPUT: Copy final chapter-outline.md to docs/outlines/chapter-{{chapter_number}}-outline.md"
|
notes: "Create detailed chapter outline using *create-chapter-outline command. Define learning objectives, prerequisites, main sections, exercises, and code examples needed. SAVE OUTPUT: Copy final chapter-outline.md to docs/outlines/chapter-{{chapter_number}}-outline.md"
|
||||||
|
|
||||||
- agent: code-curator
|
- agent: tutorial-architect
|
||||||
creates: code-examples/
|
creates: section-list.md
|
||||||
|
orchestrates: section-planning-workflow
|
||||||
requires: chapter-outline.md
|
requires: chapter-outline.md
|
||||||
notes: "Develop and test all code examples identified in outline. Use *create-example for each example. Ensure all code runs correctly, follows best practices, and includes proper error handling. SAVE OUTPUT: Commit code to repository in chapter-{{chapter_number}}/ folder with tests."
|
notes: "SECTION-DRIVEN APPROACH: Break chapter into 5-8 deliverable sections using section-planning-workflow. Each section 2-5 pages with clear acceptance criteria. Tutorial Architect and Instructional Designer identify section boundaries, create section plans, and validate learning flow. SAVE OUTPUT: docs/sections/chapter-{{chapter_number}}-section-list.md with all section plans. ALTERNATIVE: Skip this step for traditional full-chapter writing approach."
|
||||||
|
|
||||||
- agent: tutorial-architect
|
- agent: tutorial-architect
|
||||||
creates: chapter-draft.md
|
creates: completed-sections[]
|
||||||
requires:
|
orchestrates: section-development-workflow
|
||||||
- chapter-outline.md
|
requires: section-list.md
|
||||||
- code-examples/
|
notes: "SECTION-DRIVEN APPROACH: For each section in section-list, execute section-development-workflow (Code Curator develops code → Tutorial Architect writes section → Technical Reviewer reviews → Tutorial Architect finalizes). Sections can be developed in parallel if dependencies allow. Mark each section DONE when acceptance criteria met. SAVE OUTPUT: docs/sections/chapter-{{chapter_number}}/section-{{n}}-final.md for each section. ALTERNATIVE: Skip and use traditional drafting if not using section approach."
|
||||||
notes: "Write complete chapter draft using write-chapter-draft task. Include introduction, main content sections with tutorials, code examples inline, practice exercises, and summary. Ensure all learning objectives addressed. SAVE OUTPUT: Copy final draft to docs/chapters/chapter-{{chapter_number}}-draft.md"
|
|
||||||
|
|
||||||
- agent: technical-reviewer
|
|
||||||
creates: technical-review-report.md
|
|
||||||
requires: chapter-draft.md
|
|
||||||
notes: "Perform comprehensive technical review using *review-chapter command. Verify technical accuracy, test all code, check security best practices, assess performance. Use technical-accuracy-checklist, security-best-practices-checklist, and performance-considerations-checklist. SAVE OUTPUT: Copy review report to reviews/technical-review-chapter-{{chapter_number}}.md"
|
|
||||||
|
|
||||||
- agent: tutorial-architect
|
- agent: tutorial-architect
|
||||||
updates: chapter-draft.md
|
creates: chapter-integrated.md
|
||||||
requires: technical-review-report.md
|
orchestrates: chapter-assembly-workflow
|
||||||
notes: "Revise chapter based on technical review feedback. Address all Critical issues and Major issues. Update code examples if needed. Test revised code. Mark story status as 'Revision-Technical' during this phase. SAVE OUTPUT: Update chapter-draft.md with revisions."
|
requires: completed-sections[]
|
||||||
|
notes: "SECTION-DRIVEN APPROACH: Execute chapter-assembly-workflow to merge all completed sections. Tutorial Architect merges and improves transitions → Instructional Designer validates learning flow → Technical Reviewer performs full chapter review → Tutorial Architect revises → Technical Editor copy edits → Tutorial Architect finalizes. SAVE OUTPUT: docs/chapters/chapter-{{chapter_number}}-final.md. ALTERNATIVE: For traditional approach, use original sequence (code-curator develops all code → tutorial-architect writes full draft → technical-reviewer reviews → revise → copy-edit → finalize)."
|
||||||
- agent: technical-editor
|
|
||||||
updates: chapter-draft.md
|
|
||||||
requires: revised-chapter-draft.md
|
|
||||||
notes: "Perform professional copy edit using *edit-chapter command. Improve clarity, check consistency, enhance transitions, verify publisher style compliance, review accessibility. Use accessibility-checklist and publisher-specific checklist. SAVE OUTPUT: Return edited chapter with change summary."
|
|
||||||
|
|
||||||
- agent: tutorial-architect
|
- agent: tutorial-architect
|
||||||
finalizes: chapter-final.md
|
validates: chapter-final.md
|
||||||
requires: edited-chapter.md
|
requires: chapter-integrated.md
|
||||||
notes: "Review and approve editorial changes. Ensure technical accuracy preserved during editing. Create final chapter version. Mark chapter status as 'Ready for Publication'. SAVE OUTPUT: Copy final chapter to docs/chapters/chapter-{{chapter_number}}-final.md"
|
notes: "FINAL VALIDATION (both approaches): Run chapter-completeness-checklist. Verify all learning objectives addressed, code tested, quality gates passed. Mark chapter status as 'Ready for Publication'. This step ensures quality regardless of section-driven or traditional approach used."
|
||||||
|
|
||||||
flow_diagram: |
|
flow_diagram: |
|
||||||
```mermaid
|
```mermaid
|
||||||
graph TD
|
graph TD
|
||||||
A[Start: New Chapter] --> B[tutorial-architect: Create Outline]
|
A[Start: New Chapter] --> B[tutorial-architect: Create Outline]
|
||||||
B --> C[code-curator: Develop Code Examples]
|
B --> C{Section-Driven or Traditional?}
|
||||||
C --> D[tutorial-architect: Write Chapter Draft]
|
|
||||||
D --> E[technical-reviewer: Technical Review]
|
|
||||||
E --> F{Critical/Major Issues?}
|
|
||||||
F -->|Yes| G[tutorial-architect: Revise Chapter]
|
|
||||||
F -->|No| H[technical-editor: Copy Edit]
|
|
||||||
G --> I[code-curator: Update Code if Needed]
|
|
||||||
I --> E
|
|
||||||
H --> J[tutorial-architect: Review Edits]
|
|
||||||
J --> K{Approve Edits?}
|
|
||||||
K -->|Yes| L[Finalize Chapter]
|
|
||||||
K -->|No| M[Discuss with Editor]
|
|
||||||
M --> H
|
|
||||||
L --> N[Chapter Ready for Publication]
|
|
||||||
|
|
||||||
B -.-> B1[Optional: *create-learning-objectives]
|
C -->|Section-Driven v2.0| D[Plan Sections: section-planning-workflow]
|
||||||
C -.-> C1[Optional: *test-code]
|
D --> E[Develop Sections: section-development-workflow]
|
||||||
E -.-> E1[Optional: *security-audit]
|
E --> F{All Sections DONE?}
|
||||||
E -.-> E2[Optional: *verify-accuracy]
|
F -->|No| E
|
||||||
|
F -->|Yes| G[Assemble Chapter: chapter-assembly-workflow]
|
||||||
|
G --> H[Final Validation]
|
||||||
|
H --> I[Chapter Ready for Publication]
|
||||||
|
|
||||||
style N fill:#90EE90
|
C -->|Traditional| J[code-curator: Develop All Code]
|
||||||
|
J --> K[tutorial-architect: Write Full Draft]
|
||||||
|
K --> L[technical-reviewer: Review Chapter]
|
||||||
|
L --> M{Issues?}
|
||||||
|
M -->|Yes| N[Revise]
|
||||||
|
N --> L
|
||||||
|
M -->|No| O[technical-editor: Copy Edit]
|
||||||
|
O --> H
|
||||||
|
|
||||||
|
D -.-> D1[Break into 5-8 sections]
|
||||||
|
E -.-> E1[Parallel development possible]
|
||||||
|
G -.-> G1[Merge + Transitions + Review]
|
||||||
|
|
||||||
|
style I fill:#90EE90
|
||||||
style B fill:#FFE4B5
|
style B fill:#FFE4B5
|
||||||
style C fill:#FFE4B5
|
|
||||||
style D fill:#FFE4B5
|
style D fill:#FFE4B5
|
||||||
style E fill:#ADD8E6
|
style E fill:#FFE4B5
|
||||||
style H fill:#ADD8E6
|
style G fill:#ADD8E6
|
||||||
style L fill:#F0E68C
|
style H fill:#F0E68C
|
||||||
|
style J fill:#FFE4B5
|
||||||
|
style K fill:#FFE4B5
|
||||||
```
|
```
|
||||||
|
|
||||||
decision_guidance:
|
decision_guidance:
|
||||||
when_to_use:
|
when_to_use_section_driven:
|
||||||
|
- Chapters 15+ pages (too large for single sitting)
|
||||||
|
- Want incremental progress tracking ("5 of 8 sections complete")
|
||||||
|
- Need parallel development (multiple sections in progress)
|
||||||
|
- Want to review work-in-progress before full chapter done
|
||||||
|
- Prefer story-driven iterative approach (BMad analog)
|
||||||
|
|
||||||
|
when_to_use_traditional:
|
||||||
|
- Short chapters (<10-12 pages)
|
||||||
|
- Simple reference sections
|
||||||
|
- Author prefers writing full chapter at once
|
||||||
|
- Chapter already partially written
|
||||||
|
|
||||||
|
general_when_to_use:
|
||||||
- Writing technical book chapters with code examples
|
- Writing technical book chapters with code examples
|
||||||
- Creating tutorial-based training materials
|
- Creating tutorial-based training materials
|
||||||
- Developing programming books or guides
|
- Developing programming books or guides
|
||||||
|
|
@ -123,15 +132,32 @@ workflow:
|
||||||
- Checklists: accessibility-checklist, publisher-specific checklist
|
- Checklists: accessibility-checklist, publisher-specific checklist
|
||||||
|
|
||||||
handoff_prompts:
|
handoff_prompts:
|
||||||
|
section_driven_flow:
|
||||||
|
outline_to_planning: "Chapter outline complete with {{objective_count}} learning objectives and {{code_count}} code examples. Breaking into sections using section-planning-workflow."
|
||||||
|
planning_to_development: "Section planning complete. {{section_count}} sections defined. Each section 2-5 pages with clear acceptance criteria. Begin section-development-workflow for each section."
|
||||||
|
development_to_assembly: "All {{section_count}} sections DONE. Total ~{{page_count}} pages of content complete. Ready for chapter-assembly-workflow to merge and polish."
|
||||||
|
assembly_to_final: "Chapter assembly complete. All sections integrated with improved transitions. Full technical review and copy editing done. Final validation in progress."
|
||||||
|
|
||||||
|
traditional_flow:
|
||||||
architect_to_curator: "Chapter outline complete with {{code_count}} code examples identified. Save outline to docs/outlines/, then develop and test all code examples."
|
architect_to_curator: "Chapter outline complete with {{code_count}} code examples identified. Save outline to docs/outlines/, then develop and test all code examples."
|
||||||
curator_to_architect: "All code examples developed and tested in chapter-{{chapter_number}}/ folder. Tests passing. Ready for chapter draft writing."
|
curator_to_architect: "All code examples developed and tested in chapter-{{chapter_number}}/ folder. Tests passing. Ready for chapter draft writing."
|
||||||
architect_to_reviewer: "Chapter draft complete at docs/chapters/chapter-{{chapter_number}}-draft.md. All {{objective_count}} learning objectives addressed. Ready for technical review."
|
architect_to_reviewer: "Chapter draft complete at docs/chapters/chapter-{{chapter_number}}-draft.md. All {{objective_count}} learning objectives addressed. Ready for technical review."
|
||||||
reviewer_to_architect: "Technical review complete. Found {{critical_count}} critical, {{major_count}} major, and {{minor_count}} minor issues. Review report at reviews/technical-review-chapter-{{chapter_number}}.md. Please address and revise."
|
reviewer_to_architect: "Technical review complete. Found {{critical_count}} critical, {{major_count}} major, and {{minor_count}} minor issues. Review report at reviews/technical-review-chapter-{{chapter_number}}.md. Please address and revise."
|
||||||
revised_to_editor: "Technical review issues addressed. Revised chapter ready for copy editing."
|
revised_to_editor: "Technical review issues addressed. Revised chapter ready for copy editing."
|
||||||
|
|
||||||
|
both_approaches:
|
||||||
editor_to_architect: "Copy editing complete. Made improvements to clarity, consistency, and style. Change summary attached. Please review and approve."
|
editor_to_architect: "Copy editing complete. Made improvements to clarity, consistency, and style. Change summary attached. Please review and approve."
|
||||||
architect_final: "Editorial changes approved. Chapter finalized at docs/chapters/chapter-{{chapter_number}}-final.md. Status: Ready for Publication."
|
architect_final: "Editorial changes approved. Chapter finalized at docs/chapters/chapter-{{chapter_number}}-final.md. Status: Ready for Publication."
|
||||||
|
|
||||||
time_estimates:
|
time_estimates:
|
||||||
|
section_driven_approach:
|
||||||
|
create_outline: "2-4 hours"
|
||||||
|
plan_sections: "6-11 hours (section-planning-workflow)"
|
||||||
|
develop_sections: "33-84 hours (5.5-10.5 hrs per section × 6-8 sections, can be parallel)"
|
||||||
|
assemble_chapter: "13-24 hours (chapter-assembly-workflow)"
|
||||||
|
total_time: "54-123 hours per chapter (significant parallel development possible)"
|
||||||
|
|
||||||
|
traditional_approach:
|
||||||
create_outline: "2-4 hours"
|
create_outline: "2-4 hours"
|
||||||
develop_code: "4-8 hours (depending on complexity)"
|
develop_code: "4-8 hours (depending on complexity)"
|
||||||
write_draft: "12-20 hours (15-30 page chapter)"
|
write_draft: "12-20 hours (15-30 page chapter)"
|
||||||
|
|
@ -139,14 +165,31 @@ workflow:
|
||||||
revision: "4-8 hours"
|
revision: "4-8 hours"
|
||||||
copy_edit: "2-4 hours"
|
copy_edit: "2-4 hours"
|
||||||
finalization: "1-2 hours"
|
finalization: "1-2 hours"
|
||||||
total_time: "28-51 hours per chapter"
|
total_time: "28-51 hours per chapter (sequential, no parallelization)"
|
||||||
|
|
||||||
|
comparison_notes: "Section-driven has higher total time but allows parallel work and incremental progress. Traditional is faster for solo authors on short chapters."
|
||||||
|
|
||||||
best_practices:
|
best_practices:
|
||||||
|
general:
|
||||||
- Start with strong learning objectives - they guide everything
|
- Start with strong learning objectives - they guide everything
|
||||||
- Test ALL code before including in chapter
|
- Test ALL code before including in chapter
|
||||||
- Use tutorial-section-tmpl for hands-on sections
|
|
||||||
- Progressive difficulty in exercises (basic to advanced)
|
|
||||||
- Get technical review before editorial polish
|
- Get technical review before editorial polish
|
||||||
- Address critical issues before moving forward
|
- Address critical issues before moving forward
|
||||||
- Maintain author voice during editing
|
- Maintain author voice during editing
|
||||||
- Keep reader learning experience as top priority
|
- Keep reader learning experience as top priority
|
||||||
|
|
||||||
|
section_driven_specific:
|
||||||
|
- Choose section-driven for chapters 15+ pages
|
||||||
|
- Plan all sections before developing any (see dependencies)
|
||||||
|
- Develop sections that have no dependencies in parallel
|
||||||
|
- Mark sections DONE only when acceptance criteria met
|
||||||
|
- Track progress: "Chapter 3: 5 of 8 sections complete"
|
||||||
|
- Review sections incrementally (catch issues early)
|
||||||
|
- Use section-driven for story-like iterative workflow
|
||||||
|
|
||||||
|
traditional_specific:
|
||||||
|
- Choose traditional for short chapters (<12 pages)
|
||||||
|
- Good for solo authors who prefer full chapter flow
|
||||||
|
- Faster for simple reference chapters
|
||||||
|
- Use tutorial-section-tmpl for hands-on sections
|
||||||
|
- Progressive difficulty in exercises (basic to advanced)
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,152 @@
|
||||||
|
workflow:
|
||||||
|
id: chapter-development-workflow
|
||||||
|
name: Write and Refine Chapter
|
||||||
|
description: Complete chapter creation workflow from outline to publisher-ready manuscript. Guides technical authors through planning, drafting, code development, technical review, and editorial polish. Emphasizes learning objectives, hands-on tutorials, tested code examples, and professional quality standards.
|
||||||
|
type: chapter-writing
|
||||||
|
project_types:
|
||||||
|
- technical-book
|
||||||
|
- tutorial-series
|
||||||
|
- training-materials
|
||||||
|
- technical-documentation
|
||||||
|
sequence:
|
||||||
|
- agent: tutorial-architect
|
||||||
|
creates: chapter-outline.md
|
||||||
|
requires: book-outline.md
|
||||||
|
notes: "Create detailed chapter outline using *create-chapter-outline command. Define learning objectives, prerequisites, main sections, exercises, and code examples needed. SAVE OUTPUT: Copy final chapter-outline.md to docs/outlines/chapter-{{chapter_number}}-outline.md"
|
||||||
|
|
||||||
|
- agent: code-curator
|
||||||
|
creates: code-examples/
|
||||||
|
requires: chapter-outline.md
|
||||||
|
notes: "Develop and test all code examples identified in outline. Use *create-example for each example. Ensure all code runs correctly, follows best practices, and includes proper error handling. SAVE OUTPUT: Commit code to repository in chapter-{{chapter_number}}/ folder with tests."
|
||||||
|
|
||||||
|
- agent: tutorial-architect
|
||||||
|
creates: chapter-draft.md
|
||||||
|
requires:
|
||||||
|
- chapter-outline.md
|
||||||
|
- code-examples/
|
||||||
|
notes: "Write complete chapter draft using write-chapter-draft task. Include introduction, main content sections with tutorials, code examples inline, practice exercises, and summary. Ensure all learning objectives addressed. SAVE OUTPUT: Copy final draft to docs/chapters/chapter-{{chapter_number}}-draft.md"
|
||||||
|
|
||||||
|
- agent: technical-reviewer
|
||||||
|
creates: technical-review-report.md
|
||||||
|
requires: chapter-draft.md
|
||||||
|
notes: "Perform comprehensive technical review using *review-chapter command. Verify technical accuracy, test all code, check security best practices, assess performance. Use technical-accuracy-checklist, security-best-practices-checklist, and performance-considerations-checklist. SAVE OUTPUT: Copy review report to reviews/technical-review-chapter-{{chapter_number}}.md"
|
||||||
|
|
||||||
|
- agent: tutorial-architect
|
||||||
|
updates: chapter-draft.md
|
||||||
|
requires: technical-review-report.md
|
||||||
|
notes: "Revise chapter based on technical review feedback. Address all Critical issues and Major issues. Update code examples if needed. Test revised code. Mark story status as 'Revision-Technical' during this phase. SAVE OUTPUT: Update chapter-draft.md with revisions."
|
||||||
|
|
||||||
|
- agent: technical-editor
|
||||||
|
updates: chapter-draft.md
|
||||||
|
requires: revised-chapter-draft.md
|
||||||
|
notes: "Perform professional copy edit using *edit-chapter command. Improve clarity, check consistency, enhance transitions, verify publisher style compliance, review accessibility. Use accessibility-checklist and publisher-specific checklist. SAVE OUTPUT: Return edited chapter with change summary."
|
||||||
|
|
||||||
|
- agent: tutorial-architect
|
||||||
|
finalizes: chapter-final.md
|
||||||
|
requires: edited-chapter.md
|
||||||
|
notes: "Review and approve editorial changes. Ensure technical accuracy preserved during editing. Create final chapter version. Mark chapter status as 'Ready for Publication'. SAVE OUTPUT: Copy final chapter to docs/chapters/chapter-{{chapter_number}}-final.md"
|
||||||
|
|
||||||
|
flow_diagram: |
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
A[Start: New Chapter] --> B[tutorial-architect: Create Outline]
|
||||||
|
B --> C[code-curator: Develop Code Examples]
|
||||||
|
C --> D[tutorial-architect: Write Chapter Draft]
|
||||||
|
D --> E[technical-reviewer: Technical Review]
|
||||||
|
E --> F{Critical/Major Issues?}
|
||||||
|
F -->|Yes| G[tutorial-architect: Revise Chapter]
|
||||||
|
F -->|No| H[technical-editor: Copy Edit]
|
||||||
|
G --> I[code-curator: Update Code if Needed]
|
||||||
|
I --> E
|
||||||
|
H --> J[tutorial-architect: Review Edits]
|
||||||
|
J --> K{Approve Edits?}
|
||||||
|
K -->|Yes| L[Finalize Chapter]
|
||||||
|
K -->|No| M[Discuss with Editor]
|
||||||
|
M --> H
|
||||||
|
L --> N[Chapter Ready for Publication]
|
||||||
|
|
||||||
|
B -.-> B1[Optional: *create-learning-objectives]
|
||||||
|
C -.-> C1[Optional: *test-code]
|
||||||
|
E -.-> E1[Optional: *security-audit]
|
||||||
|
E -.-> E2[Optional: *verify-accuracy]
|
||||||
|
|
||||||
|
style N fill:#90EE90
|
||||||
|
style B fill:#FFE4B5
|
||||||
|
style C fill:#FFE4B5
|
||||||
|
style D fill:#FFE4B5
|
||||||
|
style E fill:#ADD8E6
|
||||||
|
style H fill:#ADD8E6
|
||||||
|
style L fill:#F0E68C
|
||||||
|
```
|
||||||
|
|
||||||
|
decision_guidance:
|
||||||
|
when_to_use:
|
||||||
|
- Writing technical book chapters with code examples
|
||||||
|
- Creating tutorial-based training materials
|
||||||
|
- Developing programming books or guides
|
||||||
|
- Need for technical accuracy and professional polish
|
||||||
|
- Multiple review stages required
|
||||||
|
- Publisher quality standards must be met
|
||||||
|
|
||||||
|
when_not_to_use:
|
||||||
|
- Simple blog posts or articles (use simplified workflow)
|
||||||
|
- Reference documentation only (no tutorials)
|
||||||
|
- Quick drafts without review requirements
|
||||||
|
|
||||||
|
quality_gates:
|
||||||
|
outline_complete:
|
||||||
|
- Learning objectives defined (3-5)
|
||||||
|
- Prerequisites clearly stated
|
||||||
|
- All code examples identified
|
||||||
|
- Exercise plan created
|
||||||
|
- Checklist: prerequisite-clarity-checklist.md
|
||||||
|
|
||||||
|
draft_complete:
|
||||||
|
- All sections from outline present
|
||||||
|
- Code examples inline and explained
|
||||||
|
- Exercises included with hints
|
||||||
|
- Learning objectives addressed
|
||||||
|
- Checklist: chapter-completeness-checklist.md
|
||||||
|
|
||||||
|
technical_review_passed:
|
||||||
|
- No critical technical errors
|
||||||
|
- All code tested and working
|
||||||
|
- Security best practices followed
|
||||||
|
- No outdated information
|
||||||
|
- Checklists: technical-accuracy, security-best-practices, performance-considerations
|
||||||
|
|
||||||
|
editorial_complete:
|
||||||
|
- Grammar and spelling clean
|
||||||
|
- Terminology consistent
|
||||||
|
- Publisher style followed
|
||||||
|
- Accessibility requirements met
|
||||||
|
- Checklists: accessibility-checklist, publisher-specific checklist
|
||||||
|
|
||||||
|
handoff_prompts:
|
||||||
|
architect_to_curator: "Chapter outline complete with {{code_count}} code examples identified. Save outline to docs/outlines/, then develop and test all code examples."
|
||||||
|
curator_to_architect: "All code examples developed and tested in chapter-{{chapter_number}}/ folder. Tests passing. Ready for chapter draft writing."
|
||||||
|
architect_to_reviewer: "Chapter draft complete at docs/chapters/chapter-{{chapter_number}}-draft.md. All {{objective_count}} learning objectives addressed. Ready for technical review."
|
||||||
|
reviewer_to_architect: "Technical review complete. Found {{critical_count}} critical, {{major_count}} major, and {{minor_count}} minor issues. Review report at reviews/technical-review-chapter-{{chapter_number}}.md. Please address and revise."
|
||||||
|
revised_to_editor: "Technical review issues addressed. Revised chapter ready for copy editing."
|
||||||
|
editor_to_architect: "Copy editing complete. Made improvements to clarity, consistency, and style. Change summary attached. Please review and approve."
|
||||||
|
architect_final: "Editorial changes approved. Chapter finalized at docs/chapters/chapter-{{chapter_number}}-final.md. Status: Ready for Publication."
|
||||||
|
|
||||||
|
time_estimates:
|
||||||
|
create_outline: "2-4 hours"
|
||||||
|
develop_code: "4-8 hours (depending on complexity)"
|
||||||
|
write_draft: "12-20 hours (15-30 page chapter)"
|
||||||
|
technical_review: "3-5 hours"
|
||||||
|
revision: "4-8 hours"
|
||||||
|
copy_edit: "2-4 hours"
|
||||||
|
finalization: "1-2 hours"
|
||||||
|
total_time: "28-51 hours per chapter"
|
||||||
|
|
||||||
|
best_practices:
|
||||||
|
- Start with strong learning objectives - they guide everything
|
||||||
|
- Test ALL code before including in chapter
|
||||||
|
- Use tutorial-section-tmpl for hands-on sections
|
||||||
|
- Progressive difficulty in exercises (basic to advanced)
|
||||||
|
- Get technical review before editorial polish
|
||||||
|
- Address critical issues before moving forward
|
||||||
|
- Maintain author voice during editing
|
||||||
|
- Keep reader learning experience as top priority
|
||||||
|
|
@ -0,0 +1,149 @@
|
||||||
|
workflow:
|
||||||
|
id: section-development-workflow
|
||||||
|
name: Write and Review Section
|
||||||
|
description: Complete development of one section (2-5 pages) - the "story" unit of book writing. Develops code examples, writes section content, and reviews for technical accuracy. Section is DONE when it meets acceptance criteria from section plan.
|
||||||
|
type: section-writing
|
||||||
|
project_types:
|
||||||
|
- technical-book
|
||||||
|
- tutorial-series
|
||||||
|
- training-materials
|
||||||
|
- technical-documentation
|
||||||
|
sequence:
|
||||||
|
- agent: code-curator
|
||||||
|
creates: section-code-examples/
|
||||||
|
requires: section-plan.md
|
||||||
|
notes: "Develop all code examples identified in section plan. Use *create-example for each code example. Test code thoroughly - all examples must run correctly. Follow coding best practices, include error handling, and add inline comments. SAVE OUTPUT: Create code examples in chapter-{{chapter_number}}/section-{{section_number}}/ with tests."
|
||||||
|
|
||||||
|
- agent: code-curator
|
||||||
|
tests: section-code-examples/
|
||||||
|
requires: section-code-examples/
|
||||||
|
notes: "Test all code examples. Verify correct output, edge cases handled, error messages clear. Run linting and security checks. Document test results. Ensure examples demonstrate concepts clearly. SAVE OUTPUT: Test results and any bug fixes committed to repository."
|
||||||
|
|
||||||
|
- agent: tutorial-architect
|
||||||
|
creates: section-draft.md
|
||||||
|
requires:
|
||||||
|
- section-plan.md
|
||||||
|
- section-code-examples/
|
||||||
|
- chapter-outline.md
|
||||||
|
notes: "Write section content (2-5 pages). Follow section plan learning objectives and content plan. Include concept explanation, tutorial walkthrough with code examples inline, and practical applications. Address prerequisites and connect to previous sections. SAVE OUTPUT: Create docs/sections/chapter-{{chapter_number}}/section-{{section_number}}-draft.md"
|
||||||
|
|
||||||
|
- agent: technical-reviewer
|
||||||
|
reviews: section-draft.md
|
||||||
|
requires: section-draft.md
|
||||||
|
notes: "Quick technical review of section (focused review, not full chapter review). Verify technical accuracy, code correctness, and completeness of explanations. Check for security issues or bad practices. Use technical-accuracy-checklist for focused review. SAVE OUTPUT: Create section-review-notes.md with findings (critical/major/minor issues)."
|
||||||
|
|
||||||
|
- agent: tutorial-architect
|
||||||
|
revises: section-draft.md
|
||||||
|
requires: section-review-notes.md
|
||||||
|
notes: "Incorporate technical review feedback. Address all critical and major issues. Update code examples if needed (coordinate with code-curator). Re-test revised code. SAVE OUTPUT: Update section-draft.md with revisions."
|
||||||
|
|
||||||
|
- agent: tutorial-architect
|
||||||
|
finalizes: section-final.md
|
||||||
|
requires: revised-section-draft.md
|
||||||
|
notes: "Verify section meets all success criteria from section plan. Check learning objectives addressed, code tested, length appropriate (2-5 pages), transitions clear. Mark section status as DONE. SAVE OUTPUT: Create docs/sections/chapter-{{chapter_number}}/section-{{section_number}}-final.md and mark in section list as complete."
|
||||||
|
|
||||||
|
flow_diagram: |
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
A[Start: Section Plan Ready] --> B[code-curator: Develop Code Examples]
|
||||||
|
B --> C[code-curator: Test Code Examples]
|
||||||
|
C --> D{All Tests Pass?}
|
||||||
|
D -->|No| E[code-curator: Fix Code]
|
||||||
|
E --> C
|
||||||
|
D -->|Yes| F[tutorial-architect: Write Section]
|
||||||
|
F --> G[technical-reviewer: Quick Review]
|
||||||
|
G --> H{Critical Issues?}
|
||||||
|
H -->|Yes| I[tutorial-architect: Revise Section]
|
||||||
|
I --> J[Update Code if Needed?]
|
||||||
|
J -->|Yes| K[code-curator: Update Code]
|
||||||
|
K --> C
|
||||||
|
J -->|No| G
|
||||||
|
H -->|No| L[tutorial-architect: Verify Acceptance Criteria]
|
||||||
|
L --> M{Criteria Met?}
|
||||||
|
M -->|No| N[Address Missing Items]
|
||||||
|
N --> L
|
||||||
|
M -->|Yes| O[Section DONE]
|
||||||
|
|
||||||
|
B -.-> B1[Use section plan code list]
|
||||||
|
F -.-> F1[Reference section-plan objectives]
|
||||||
|
G -.-> G1[Use technical-accuracy-checklist]
|
||||||
|
L -.-> L1[Check section plan success criteria]
|
||||||
|
|
||||||
|
style O fill:#90EE90
|
||||||
|
style B fill:#FFE4B5
|
||||||
|
style C fill:#FFE4B5
|
||||||
|
style F fill:#FFE4B5
|
||||||
|
style G fill:#ADD8E6
|
||||||
|
style L fill:#F0E68C
|
||||||
|
```
|
||||||
|
|
||||||
|
decision_guidance:
|
||||||
|
when_to_use:
|
||||||
|
- Developing one section (2-5 pages) from section plan
|
||||||
|
- Incremental chapter development approach
|
||||||
|
- Want focused work units with clear done criteria
|
||||||
|
- Tracking progress section by section
|
||||||
|
- Parallel section development needed
|
||||||
|
|
||||||
|
when_not_to_use:
|
||||||
|
- Writing entire chapter at once (use chapter-development-workflow)
|
||||||
|
- Simple reference sections without code
|
||||||
|
- Section already written (use for new sections only)
|
||||||
|
|
||||||
|
quality_gates:
|
||||||
|
code_complete:
|
||||||
|
- All section code examples developed
|
||||||
|
- All code tested and passing
|
||||||
|
- Code follows best practices
|
||||||
|
- Examples demonstrate concepts clearly
|
||||||
|
- Error handling included
|
||||||
|
- Inline comments present
|
||||||
|
|
||||||
|
draft_complete:
|
||||||
|
- Section length 2-5 pages (appropriate granularity)
|
||||||
|
- Learning objective(s) addressed
|
||||||
|
- Code examples integrated and explained
|
||||||
|
- Tutorial walkthrough clear and step-by-step
|
||||||
|
- Prerequisites referenced
|
||||||
|
- Transitions to next section present
|
||||||
|
|
||||||
|
technical_review_passed:
|
||||||
|
- No critical technical errors
|
||||||
|
- Code accurate and tested
|
||||||
|
- Explanations technically correct
|
||||||
|
- No security issues or bad practices
|
||||||
|
- Checklist: technical-accuracy-checklist.md
|
||||||
|
|
||||||
|
section_done:
|
||||||
|
- All success criteria from section plan met
|
||||||
|
- Technical review approved
|
||||||
|
- Code tested and working
|
||||||
|
- Length appropriate (2-5 pages)
|
||||||
|
- Ready to integrate into chapter
|
||||||
|
|
||||||
|
handoff_prompts:
|
||||||
|
plan_to_curator: "Section plan complete: {{section_title}}. Learning objective: {{objective}}. {{code_count}} code examples needed. Develop and test all code."
|
||||||
|
curator_to_architect: "Code examples complete for {{section_title}}. All {{example_count}} examples tested and passing. Code in chapter-{{chapter_number}}/section-{{section_number}}/. Ready for section writing."
|
||||||
|
architect_to_reviewer: "Section draft complete: {{section_title}} ({{page_count}} pages). Learning objective addressed with {{example_count}} code examples. Quick technical review needed."
|
||||||
|
reviewer_to_architect: "Technical review complete. Found {{critical_count}} critical and {{major_count}} major issues. Review notes available. Please revise and address."
|
||||||
|
architect_final: "Section {{section_id}} DONE. All acceptance criteria met. {{page_count}} pages with {{example_count}} tested code examples. Section marked complete in section list."
|
||||||
|
|
||||||
|
time_estimates:
|
||||||
|
develop_code: "1-2 hours (per section, 1-3 examples)"
|
||||||
|
test_code: "30 minutes - 1 hour"
|
||||||
|
write_section: "2-4 hours (2-5 pages)"
|
||||||
|
technical_review: "30 minutes - 1 hour (focused section review)"
|
||||||
|
revise_section: "1-2 hours"
|
||||||
|
verify_criteria: "30 minutes"
|
||||||
|
total_time: "5.5-10.5 hours per section"
|
||||||
|
|
||||||
|
best_practices:
|
||||||
|
- Start with code - test it before writing explanations
|
||||||
|
- Follow section plan learning objectives closely
|
||||||
|
- Keep section focused (1-2 objectives max)
|
||||||
|
- Section should be independently reviewable
|
||||||
|
- Mark section DONE only when ALL criteria met
|
||||||
|
- Good sections are 2-5 pages (not too small, not too large)
|
||||||
|
- Each section is a natural stopping point
|
||||||
|
- Connect to previous section, preview next section
|
||||||
|
- Technical review is focused (not full chapter review)
|
||||||
|
|
@ -0,0 +1,121 @@
|
||||||
|
workflow:
|
||||||
|
id: section-planning-workflow
|
||||||
|
name: Plan Chapter Sections
|
||||||
|
description: Break chapter outline into deliverable section units (BMad story analog). Creates section-level work items with acceptance criteria, enabling incremental chapter development. Each section is 2-5 pages with clear learning objectives and success criteria.
|
||||||
|
type: section-planning
|
||||||
|
project_types:
|
||||||
|
- technical-book
|
||||||
|
- tutorial-series
|
||||||
|
- training-materials
|
||||||
|
- technical-documentation
|
||||||
|
sequence:
|
||||||
|
- agent: tutorial-architect
|
||||||
|
creates: section-analysis.md
|
||||||
|
requires: chapter-outline.md
|
||||||
|
notes: "Analyze chapter outline structure. Review learning objectives, main sections, and code examples. Identify natural breaking points for sections (2-5 pages each). Consider logical learning progression and dependencies between concepts. SAVE OUTPUT: Create section-analysis.md documenting chapter structure."
|
||||||
|
|
||||||
|
- agent: tutorial-architect
|
||||||
|
creates: preliminary-section-list.md
|
||||||
|
requires: section-analysis.md
|
||||||
|
notes: "Break chapter into 5-8 logical sections. Each section should teach 1-2 concepts, include 1-3 code examples, and be 2-5 pages. Name each section clearly. Define what each section teaches. Identify dependencies (which sections must come first). SAVE OUTPUT: Create preliminary-section-list.md with section titles and brief descriptions."
|
||||||
|
|
||||||
|
- agent: tutorial-architect
|
||||||
|
creates: section-plans/
|
||||||
|
requires: preliminary-section-list.md
|
||||||
|
notes: "For each section, create detailed section plan using section-plan-tmpl.yaml. Define learning objectives (1-2 max), prerequisites, content plan, code examples needed, success criteria, and dependencies. Use *create-doc with section-plan-tmpl to generate each plan. SAVE OUTPUT: Create section-plans/section-{{n}}.md for each section."
|
||||||
|
|
||||||
|
- agent: instructional-designer
|
||||||
|
reviews: section-plans/
|
||||||
|
requires: section-plans/
|
||||||
|
notes: "Validate learning flow across all sections. Verify sections scaffold properly (each builds on previous). Check that prerequisites are met in correct order. Ensure no learning gaps or concept jumps. Verify section granularity is appropriate (not too small, not too large). SAVE OUTPUT: Create section-flow-validation.md with approval or revision recommendations."
|
||||||
|
|
||||||
|
- agent: tutorial-architect
|
||||||
|
finalizes: section-list-final.md
|
||||||
|
requires: section-flow-validation.md
|
||||||
|
notes: "Incorporate instructional designer feedback. Adjust section order, prerequisites, or granularity if needed. Create final prioritized section list with dependencies mapped. Number sections sequentially. Mark any sections that can be developed in parallel. SAVE OUTPUT: Create docs/sections/chapter-{{chapter_number}}-section-list.md as authoritative section plan."
|
||||||
|
|
||||||
|
flow_diagram: |
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
A[Start: Chapter Outline Ready] --> B[tutorial-architect: Analyze Chapter Structure]
|
||||||
|
B --> C[tutorial-architect: Identify Section Boundaries]
|
||||||
|
C --> D[tutorial-architect: Create Section Plans]
|
||||||
|
D --> E[instructional-designer: Validate Learning Flow]
|
||||||
|
E --> F{Flow Issues?}
|
||||||
|
F -->|Yes| G[tutorial-architect: Adjust Sections]
|
||||||
|
G --> D
|
||||||
|
F -->|No| H[tutorial-architect: Finalize Section List]
|
||||||
|
H --> I[Section Plans Ready for Development]
|
||||||
|
|
||||||
|
D -.-> D1[Use section-plan-tmpl.yaml]
|
||||||
|
E -.-> E1[Check: Proper scaffolding]
|
||||||
|
E -.-> E2[Check: No learning gaps]
|
||||||
|
H -.-> H1[Mark parallel-safe sections]
|
||||||
|
|
||||||
|
style I fill:#90EE90
|
||||||
|
style B fill:#FFE4B5
|
||||||
|
style C fill:#FFE4B5
|
||||||
|
style D fill:#FFE4B5
|
||||||
|
style E fill:#ADD8E6
|
||||||
|
style H fill:#F0E68C
|
||||||
|
```
|
||||||
|
|
||||||
|
decision_guidance:
|
||||||
|
when_to_use:
|
||||||
|
- Breaking down chapter outline into work units
|
||||||
|
- Need incremental development approach
|
||||||
|
- Want to track section-by-section progress
|
||||||
|
- Planning parallel section development
|
||||||
|
- Chapter is 15+ pages (needs breakdown)
|
||||||
|
|
||||||
|
when_not_to_use:
|
||||||
|
- Short chapters (<10 pages) can be written as single unit
|
||||||
|
- Simple reference sections without tutorials
|
||||||
|
- Already have section breakdown from outline
|
||||||
|
|
||||||
|
quality_gates:
|
||||||
|
analysis_complete:
|
||||||
|
- Chapter structure understood
|
||||||
|
- Natural section boundaries identified
|
||||||
|
- Learning progression mapped
|
||||||
|
- Code example distribution planned
|
||||||
|
|
||||||
|
section_plans_complete:
|
||||||
|
- 5-8 sections defined (typical)
|
||||||
|
- Each section has clear learning objective
|
||||||
|
- Prerequisites identified for each section
|
||||||
|
- Success criteria defined per section
|
||||||
|
- Dependencies mapped
|
||||||
|
- Checklist: section-plan-tmpl validates
|
||||||
|
|
||||||
|
learning_flow_validated:
|
||||||
|
- Sections scaffold properly
|
||||||
|
- No learning gaps between sections
|
||||||
|
- Prerequisites met in correct order
|
||||||
|
- Section granularity appropriate (2-5 pages each)
|
||||||
|
- Parallel development opportunities identified
|
||||||
|
|
||||||
|
handoff_prompts:
|
||||||
|
outline_to_analysis: "Chapter outline complete with {{objective_count}} learning objectives. Analyze structure and identify section boundaries for incremental development."
|
||||||
|
analysis_to_sections: "Chapter analysis complete. Identified {{section_count}} natural section boundaries. Create detailed section plans for each unit."
|
||||||
|
sections_to_designer: "{{section_count}} section plans created. Each section 2-5 pages with clear objectives. Please validate learning flow and scaffolding."
|
||||||
|
designer_to_architect: "Learning flow validated. {{issue_count}} adjustments recommended. Sections scaffold properly with dependencies mapped."
|
||||||
|
architect_final: "Section list finalized. {{section_count}} sections ready for development. {{parallel_count}} sections can be developed in parallel. Section list saved to docs/sections/chapter-{{chapter_number}}-section-list.md"
|
||||||
|
|
||||||
|
time_estimates:
|
||||||
|
analyze_chapter: "1-2 hours"
|
||||||
|
identify_sections: "1-2 hours"
|
||||||
|
create_section_plans: "2-4 hours (30-45 min per section)"
|
||||||
|
validate_flow: "1-2 hours"
|
||||||
|
finalize_list: "1 hour"
|
||||||
|
total_time: "6-11 hours per chapter"
|
||||||
|
|
||||||
|
best_practices:
|
||||||
|
- Aim for 5-8 sections per chapter (typical)
|
||||||
|
- Each section should be 2-5 pages (manageable unit)
|
||||||
|
- Section = 1-2 learning objectives (not more)
|
||||||
|
- Each section should have clear "done" criteria
|
||||||
|
- Map dependencies to enable parallel development
|
||||||
|
- Consider code example distribution across sections
|
||||||
|
- Test section boundaries with reader perspective
|
||||||
|
- Sections should feel like natural stopping points
|
||||||
Loading…
Reference in New Issue