docs: add comprehensive documentation suite for sprint 6
This commit is contained in:
Joshua Magady
parent
ff94e05cd8
commit
0fb8de2e82
|
|
@ -27,10 +27,15 @@ The Technical Writing Expansion Pack extends BMad-Method with a comprehensive su
|
||||||
### 📚 Complete Documentation
|
### 📚 Complete Documentation
|
||||||
- **[Documentation Index](docs/README.md)** - Navigation hub for all documentation
|
- **[Documentation Index](docs/README.md)** - Navigation hub for all documentation
|
||||||
- **[Process Flows](docs/process-flows.md)** - Visual workflow diagrams
|
- **[Process Flows](docs/process-flows.md)** - Visual workflow diagrams
|
||||||
|
- **[Agent Reference Guide](docs/agent-reference.md)** - All 13 agents in detail
|
||||||
|
- **[Workflow Guide](docs/workflow-guide.md)** - All 15 workflows explained
|
||||||
|
- **[Template Gallery](docs/template-gallery.md)** - All 18 templates with examples
|
||||||
|
- **[Task Reference](docs/task-reference.md)** - All 33 tasks organized by phase
|
||||||
|
- **[Checklist Reference](docs/checklist-reference.md)** - All 31 checklists with quality gates
|
||||||
- **[FAQ](docs/faq.md)** - Frequently asked questions
|
- **[FAQ](docs/faq.md)** - Frequently asked questions
|
||||||
- **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions
|
- **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions
|
||||||
|
|
||||||
**See [docs/README.md](docs/README.md) for complete documentation map with 13 guides + 4 examples.**
|
**See [docs/README.md](docs/README.md) for complete documentation map with 13 guides + 4 examples (~35,000 words).**
|
||||||
|
|
||||||
## ✍️ Included Agents
|
## ✍️ Included Agents
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -295,9 +295,9 @@ Choose the path that matches your goal:
|
||||||
- ✅ 33 tasks referenced
|
- ✅ 33 tasks referenced
|
||||||
- ✅ 31 checklists detailed
|
- ✅ 31 checklists detailed
|
||||||
|
|
||||||
**Word Count**: ~30,000+ words of comprehensive documentation
|
**Word Count**: ~35,000+ words of comprehensive documentation
|
||||||
|
|
||||||
**Time to Read Everything**: ~8-10 hours (not required - read what you need!)
|
**Time to Read Everything**: ~10-12 hours (not required - read what you need!)
|
||||||
|
|
||||||
**Time to Productivity**: ~2-3 hours (Quick Reference + Getting Started Tutorial + User Guide)
|
**Time to Productivity**: ~2-3 hours (Quick Reference + Getting Started Tutorial + User Guide)
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,996 @@
|
||||||
|
# Agent Reference Guide
|
||||||
|
|
||||||
|
## Introduction
|
||||||
|
|
||||||
|
The BMad Technical Writing Expansion Pack provides **13 specialized AI agents** designed to support every phase of technical book authorship—from planning to publication. Each agent is a specialized persona with specific expertise, commands, dependencies, and integration patterns.
|
||||||
|
|
||||||
|
This comprehensive reference guide documents all 13 agents, organized by category, with detailed information about:
|
||||||
|
|
||||||
|
- **Purpose and role** - What the agent does and their expertise
|
||||||
|
- **When to use** - Specific scenarios where this agent is most effective
|
||||||
|
- **Key commands** - All available commands with descriptions
|
||||||
|
- **Dependencies** - Templates, tasks, checklists, and data files used
|
||||||
|
- **Usage examples** - Real command sequences for common scenarios
|
||||||
|
- **Integration patterns** - Which other agents they work with
|
||||||
|
|
||||||
|
### Agent Categories
|
||||||
|
|
||||||
|
- **Core Planning Agents (3)**: Design book structure, learning architecture, and content organization
|
||||||
|
- **Core Review Agents (2)**: Ensure technical accuracy and editorial polish
|
||||||
|
- **Core Publishing Agent (1)**: Prepare manuscripts for submission
|
||||||
|
- **Specialist Agents (3)**: Handle API docs, visual documentation, and exercises
|
||||||
|
- **Brownfield Agent (1)**: Analyze existing books and plan revisions
|
||||||
|
- **Optional Agents (3)**: Provide advanced capabilities for complex scenarios
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Core Planning Agents
|
||||||
|
|
||||||
|
These agents are essential for the planning and drafting phases of technical book writing.
|
||||||
|
|
||||||
|
### 🎓 Instructional Designer
|
||||||
|
|
||||||
|
**Agent ID**: `instructional-designer`
|
||||||
|
**Title**: Learning Architecture Specialist
|
||||||
|
|
||||||
|
#### Purpose and Role
|
||||||
|
|
||||||
|
Expert in learning experience architecture and pedagogical structure. Masters Bloom's taxonomy, scaffolding principles, cognitive load theory, and adult learning methodologies. Designs book structures and learning paths that enable readers to successfully master technical content.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Designing overall book outlines with learning-focused chapter progression
|
||||||
|
- Creating learning objectives for chapters and sections
|
||||||
|
- Mapping prerequisite knowledge and scaffolding sequences
|
||||||
|
- Analyzing difficulty curves to ensure proper learning progression
|
||||||
|
- Designing assessment strategies aligned with learning objectives
|
||||||
|
- Applying pedagogical frameworks (Bloom's taxonomy, cognitive load theory)
|
||||||
|
|
||||||
|
#### Key Commands
|
||||||
|
|
||||||
|
- `*help` - Show numbered list of available commands
|
||||||
|
- `*create-book-outline` - Runs `design-book-outline.md` task to create pedagogically sound book structure
|
||||||
|
- `*create-learning-objectives` - Runs `create-learning-objectives.md` task to define measurable learning outcomes
|
||||||
|
- `*design-learning-path` - Maps prerequisite dependencies and skill progression
|
||||||
|
- `*analyze-difficulty-curve` - Ensures proper learning progression across chapters
|
||||||
|
- `*design-assessment-strategy` - Creates exercises and quizzes aligned with objectives
|
||||||
|
- `*apply-learning-framework` - Applies Bloom's taxonomy or other pedagogical frameworks
|
||||||
|
- `*exit` - Exits persona
|
||||||
|
|
||||||
|
#### Dependencies
|
||||||
|
|
||||||
|
**Tasks**: `create-doc.md`, `design-book-outline.md`, `create-learning-objectives.md`, `execute-checklist.md`
|
||||||
|
**Templates**: `book-outline-tmpl.yaml`, `chapter-outline-tmpl.yaml`
|
||||||
|
**Checklists**: `learning-objectives-checklist.md`, `prerequisite-clarity-checklist.md`
|
||||||
|
**Data**: `bmad-kb.md`, `learning-frameworks.md`, `book-structures.md`
|
||||||
|
|
||||||
|
#### Usage Example
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start Instructional Designer
|
||||||
|
/BMad:agents:instructional-designer
|
||||||
|
|
||||||
|
# Create book outline for "Python Data Structures Handbook"
|
||||||
|
*create-book-outline
|
||||||
|
# Agent elicits: book topic, target audience, prerequisites, learning goals
|
||||||
|
# Output: book-outline.md with 10 chapters, learning progression
|
||||||
|
|
||||||
|
# Create learning objectives for Chapter 3
|
||||||
|
*create-learning-objectives
|
||||||
|
# Agent elicits: chapter topic, target Bloom's level, prior knowledge
|
||||||
|
# Output: learning-objectives.md with measurable outcomes
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Integration Patterns
|
||||||
|
|
||||||
|
- **Works with Tutorial Architect**: Instructional Designer defines learning objectives → Tutorial Architect designs tutorials to meet them
|
||||||
|
- **Works with Exercise Creator**: Provides learning objectives → Exercise Creator designs aligned assessments
|
||||||
|
- **Works with Learning Path Designer**: Collaborates on prerequisite mapping and skill scaffolding
|
||||||
|
- **Feeds into**: Chapter development workflows, learning objective validation
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 📝 Tutorial Architect
|
||||||
|
|
||||||
|
**Agent ID**: `tutorial-architect`
|
||||||
|
**Title**: Hands-On Instruction Specialist
|
||||||
|
|
||||||
|
#### Purpose and Role
|
||||||
|
|
||||||
|
Expert in hands-on instruction and step-by-step learning design. Specializes in breaking down complex topics into actionable steps, creating effective tutorials where readers can follow along and build working solutions.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Creating step-by-step tutorial sections
|
||||||
|
- Designing chapter outlines with hands-on exercises
|
||||||
|
- Writing detailed walkthroughs and how-to guides
|
||||||
|
- Adding troubleshooting sections for common issues
|
||||||
|
- Designing practice exercises and challenges
|
||||||
|
- Writing chapter summaries and key takeaways
|
||||||
|
|
||||||
|
#### Key Commands
|
||||||
|
|
||||||
|
- `*help` - Show numbered list of available commands
|
||||||
|
- `*create-tutorial` - Designs hands-on tutorial section with clear steps
|
||||||
|
- `*outline-chapter` - Runs `create-chapter-outline.md` task to structure tutorial-based chapters
|
||||||
|
- `*write-walkthrough` - Creates detailed step-by-step guide with expected outcomes
|
||||||
|
- `*add-troubleshooting` - Documents common issues and their solutions
|
||||||
|
- `*design-exercises` - Creates practice problems and hands-on activities
|
||||||
|
- `*write-summary` - Creates chapter recap and key takeaways
|
||||||
|
- `*exit` - Exits persona
|
||||||
|
|
||||||
|
#### Dependencies
|
||||||
|
|
||||||
|
**Tasks**: `create-doc.md`, `create-chapter-outline.md`, `execute-checklist.md`
|
||||||
|
**Templates**: `chapter-outline-tmpl.yaml`
|
||||||
|
**Checklists**: `tutorial-effectiveness-checklist.md`, `chapter-completeness-checklist.md`, `exercise-difficulty-checklist.md`
|
||||||
|
**Data**: `bmad-kb.md`, `learning-frameworks.md`, `book-structures.md`
|
||||||
|
|
||||||
|
#### Usage Example
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start Tutorial Architect
|
||||||
|
/BMad:agents:tutorial-architect
|
||||||
|
|
||||||
|
# Create chapter outline for tutorial-heavy chapter
|
||||||
|
*outline-chapter
|
||||||
|
# Agent elicits: chapter topic, target skills, prerequisites
|
||||||
|
# Output: chapter-outline.md with tutorial steps, exercises, troubleshooting
|
||||||
|
|
||||||
|
# Create walkthrough for "Building Your First Binary Tree"
|
||||||
|
*write-walkthrough
|
||||||
|
# Agent guides creation of step-by-step tutorial
|
||||||
|
# Output: Tutorial section with clear steps, expected results, troubleshooting
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Integration Patterns
|
||||||
|
|
||||||
|
- **Works with Instructional Designer**: Receives learning objectives → Creates tutorials to teach them
|
||||||
|
- **Works with Code Curator**: Tutorial Architect designs tutorial flow → Code Curator ensures all code works
|
||||||
|
- **Works with Exercise Creator**: Creates tutorial content → Exercise Creator adds practice problems
|
||||||
|
- **Feeds into**: Chapter development workflows, section-driven development
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 💻 Code Curator
|
||||||
|
|
||||||
|
**Agent ID**: `code-curator`
|
||||||
|
**Title**: Code Example Quality Guardian
|
||||||
|
|
||||||
|
#### Purpose and Role
|
||||||
|
|
||||||
|
Expert in code quality, testing, and example craftsmanship. Ensures every code example works perfectly on first try, follows best practices, and is thoroughly tested across specified versions and platforms.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Creating tested, production-quality code examples
|
||||||
|
- Testing all code examples across versions and platforms
|
||||||
|
- Verifying version compatibility for specified tech stacks
|
||||||
|
- Optimizing code examples for clarity and efficiency
|
||||||
|
- Debugging and troubleshooting code example issues
|
||||||
|
- Ensuring code follows language-specific style guides
|
||||||
|
|
||||||
|
#### Key Commands
|
||||||
|
|
||||||
|
- `*help` - Show numbered list of available commands
|
||||||
|
- `*create-code-example` - Runs `create-code-example.md` task to build tested code snippets
|
||||||
|
- `*test-all-examples` - Runs `test-code-examples.md` task to validate all code
|
||||||
|
- `*version-check` - Verifies version compatibility across specified versions
|
||||||
|
- `*optimize-code` - Improves example clarity, efficiency, and best practices
|
||||||
|
- `*troubleshoot-example` - Debugs common issues in code examples
|
||||||
|
- `*exit` - Exits persona
|
||||||
|
|
||||||
|
#### Dependencies
|
||||||
|
|
||||||
|
**Tasks**: `create-code-example.md`, `test-code-examples.md`, `execute-checklist.md`
|
||||||
|
**Templates**: `code-example-tmpl.yaml`
|
||||||
|
**Checklists**: `code-quality-checklist.md`, `code-testing-checklist.md`, `version-compatibility-checklist.md`
|
||||||
|
**Data**: `bmad-kb.md`, `code-style-guides.md`
|
||||||
|
|
||||||
|
#### Usage Example
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start Code Curator
|
||||||
|
/BMad:agents:code-curator
|
||||||
|
|
||||||
|
# Create code example for binary search tree insertion
|
||||||
|
*create-code-example
|
||||||
|
# Agent elicits: language, concept to demonstrate, versions
|
||||||
|
# Output: Fully tested code example with comments, error handling
|
||||||
|
|
||||||
|
# Test all examples in chapter
|
||||||
|
*test-all-examples
|
||||||
|
# Agent runs tests, reports failures, suggests fixes
|
||||||
|
# Output: Test report with pass/fail status for each example
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Integration Patterns
|
||||||
|
|
||||||
|
- **Works with Tutorial Architect**: Receives code requirements from tutorials → Creates tested, working code
|
||||||
|
- **Works with Sample Code Maintainer**: Creates examples → Sample Code Maintainer organizes into repository
|
||||||
|
- **Works with Version Manager**: Collaborates on multi-version testing and compatibility
|
||||||
|
- **Feeds into**: Code example workflows, technical review processes
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Core Review Agents
|
||||||
|
|
||||||
|
These agents ensure content quality through technical validation and editorial refinement.
|
||||||
|
|
||||||
|
### 🔍 Technical Reviewer
|
||||||
|
|
||||||
|
**Agent ID**: `technical-reviewer`
|
||||||
|
**Title**: Subject Matter Expert & Technical Validator
|
||||||
|
|
||||||
|
#### Purpose and Role
|
||||||
|
|
||||||
|
Subject matter expert focused on ensuring technical accuracy, security, and best practices. Validates technical content thoroughly while providing constructive guidance for improvement.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Conducting comprehensive technical reviews of chapters
|
||||||
|
- Verifying technical accuracy against official documentation
|
||||||
|
- Checking code examples for correctness and best practices
|
||||||
|
- Identifying security vulnerabilities and unsafe patterns
|
||||||
|
- Assessing performance implications of recommended approaches
|
||||||
|
- Ensuring information is current and not outdated
|
||||||
|
- Providing constructive technical feedback
|
||||||
|
|
||||||
|
#### Key Commands
|
||||||
|
|
||||||
|
- `*help` - Show numbered list of available commands
|
||||||
|
- `*review-chapter` - Runs `technical-review-chapter.md` task for comprehensive chapter review
|
||||||
|
- `*verify-accuracy` - Checks technical facts against official documentation
|
||||||
|
- `*check-best-practices` - Validates code and recommendations follow industry standards
|
||||||
|
- `*identify-errors` - Finds technical inaccuracies, bugs, or misconceptions
|
||||||
|
- `*suggest-improvements` - Provides constructive recommendations for enhancements
|
||||||
|
- `*security-audit` - Reviews code examples for security issues
|
||||||
|
- `*exit` - Exits persona
|
||||||
|
|
||||||
|
#### Dependencies
|
||||||
|
|
||||||
|
**Tasks**: `create-doc.md`, `technical-review-chapter.md`, `execute-checklist.md`
|
||||||
|
**Templates**: `technical-review-report-tmpl.yaml`
|
||||||
|
**Checklists**: `technical-accuracy-checklist.md`, `security-best-practices-checklist.md`, `performance-considerations-checklist.md`
|
||||||
|
**Data**: `bmad-kb.md`, `technical-writing-standards.md`
|
||||||
|
|
||||||
|
#### Usage Example
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start Technical Reviewer
|
||||||
|
/BMad:agents:technical-reviewer
|
||||||
|
|
||||||
|
# Review Chapter 5 for technical accuracy
|
||||||
|
*review-chapter
|
||||||
|
# Agent reads chapter, checks facts, validates code
|
||||||
|
# Output: technical-review-report.md with findings, severity, recommendations
|
||||||
|
|
||||||
|
# Security audit for code examples
|
||||||
|
*security-audit
|
||||||
|
# Agent scans for SQL injection, XSS, hardcoded secrets, etc.
|
||||||
|
# Output: Security findings with severity levels and remediation steps
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Integration Patterns
|
||||||
|
|
||||||
|
- **Works with Code Curator**: Reviews Code Curator's examples for correctness and best practices
|
||||||
|
- **Works with Technical Editor**: Technical Reviewer validates accuracy → Technical Editor improves clarity
|
||||||
|
- **Receives from**: All content-creating agents (Instructional Designer, Tutorial Architect, etc.)
|
||||||
|
- **Feeds into**: Technical review workflows, revision planning
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### ✍️ Technical Editor
|
||||||
|
|
||||||
|
**Agent ID**: `technical-editor`
|
||||||
|
**Title**: Technical Communication Expert & Copy Editor
|
||||||
|
|
||||||
|
#### Purpose and Role
|
||||||
|
|
||||||
|
Expert in technical writing style, clarity, consistency, flow, and publisher requirements. Transforms technically accurate content into professionally polished, reader-friendly material ready for publication.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Copy editing chapters for grammar, spelling, and style
|
||||||
|
- Improving sentence clarity and readability
|
||||||
|
- Checking terminology and style consistency
|
||||||
|
- Enhancing transitions between sections and chapters
|
||||||
|
- Verifying compliance with publisher style guidelines
|
||||||
|
- Ensuring accessibility for diverse readers
|
||||||
|
- Providing professional polish before submission
|
||||||
|
|
||||||
|
#### Key Commands
|
||||||
|
|
||||||
|
- `*help` - Show numbered list of available commands
|
||||||
|
- `*edit-chapter` - Runs `copy-edit-chapter.md` for comprehensive editorial review
|
||||||
|
- `*improve-clarity` - Enhances sentence clarity and readability
|
||||||
|
- `*check-consistency` - Verifies terminology, style, and formatting consistency
|
||||||
|
- `*enhance-transitions` - Improves flow between sections and chapters
|
||||||
|
- `*copy-edit` - Performs professional copy editing (grammar, spelling, style)
|
||||||
|
- `*check-publisher-style` - Verifies compliance with specific publisher guidelines
|
||||||
|
- `*exit` - Exits persona
|
||||||
|
|
||||||
|
#### Dependencies
|
||||||
|
|
||||||
|
**Tasks**: `create-doc.md`, `copy-edit-chapter.md`, `execute-checklist.md`
|
||||||
|
**Checklists**: `packtpub-submission-checklist.md`, `oreilly-format-checklist.md`, `manning-meap-checklist.md`, `accessibility-checklist.md`
|
||||||
|
**Data**: `bmad-kb.md`, `publisher-guidelines.md`, `code-style-guides.md`, `technical-writing-standards.md`
|
||||||
|
|
||||||
|
#### Usage Example
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start Technical Editor
|
||||||
|
/BMad:agents:technical-editor
|
||||||
|
|
||||||
|
# Copy edit Chapter 3 for clarity and consistency
|
||||||
|
*edit-chapter
|
||||||
|
# Agent reviews for clarity, grammar, style, consistency
|
||||||
|
# Output: Edited chapter with tracked changes and style notes
|
||||||
|
|
||||||
|
# Check for O'Reilly compliance
|
||||||
|
*check-publisher-style
|
||||||
|
# Agent elicits: target publisher (O'Reilly selected)
|
||||||
|
# Output: Compliance report with formatting adjustments needed
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Integration Patterns
|
||||||
|
|
||||||
|
- **Works with Technical Reviewer**: Technical Reviewer validates accuracy → Technical Editor polishes clarity
|
||||||
|
- **Works with Book Publisher**: Technical Editor ensures quality → Book Publisher handles formatting
|
||||||
|
- **Receives from**: All content-creating agents after technical review
|
||||||
|
- **Feeds into**: Publishing workflows, final submission preparation
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Core Publishing Agent
|
||||||
|
|
||||||
|
### 📦 Book Publisher
|
||||||
|
|
||||||
|
**Agent ID**: `book-publisher`
|
||||||
|
**Title**: Publication Specialist & Manuscript Packager
|
||||||
|
|
||||||
|
#### Purpose and Role
|
||||||
|
|
||||||
|
Expert in publisher requirements, submission processes, and professional manuscript packaging for traditional and self-publishing. Transforms finished manuscripts into professionally packaged submissions that meet exact publisher requirements.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Preparing book proposals for publishers
|
||||||
|
- Packaging complete manuscripts for submission
|
||||||
|
- Formatting for specific publishers (PacktPub, O'Reilly, Manning)
|
||||||
|
- Preparing chapters for Manning Early Access Program (MEAP)
|
||||||
|
- Formatting manuscripts for self-publishing platforms
|
||||||
|
- Creating book indexes from marked terms
|
||||||
|
- Ensuring all supplementary materials are ready
|
||||||
|
|
||||||
|
#### Key Commands
|
||||||
|
|
||||||
|
- `*help` - Show numbered list of available commands
|
||||||
|
- `*prepare-proposal` - Uses `book-proposal-tmpl` to create publisher proposal
|
||||||
|
- `*package-manuscript` - Organizes and formats complete manuscript for submission
|
||||||
|
- `*format-for-packtpub` - Applies PacktPub-specific formatting and requirements
|
||||||
|
- `*format-for-oreilly` - Applies O'Reilly-specific formatting (AsciiDoc, Chicago style)
|
||||||
|
- `*prepare-meap` - Formats chapter for Manning Early Access Program
|
||||||
|
- `*self-publish-prep` - Prepares manuscript for self-publishing platforms
|
||||||
|
- `*create-index` - Generates book index from marked terms
|
||||||
|
- `*exit` - Exits persona
|
||||||
|
|
||||||
|
#### Dependencies
|
||||||
|
|
||||||
|
**Tasks**: `create-doc.md`, `execute-checklist.md`
|
||||||
|
**Templates**: `book-proposal-tmpl.yaml`, `introduction-tmpl.yaml`
|
||||||
|
**Checklists**: `packtpub-submission-checklist.md`, `oreilly-format-checklist.md`, `manning-meap-checklist.md`
|
||||||
|
**Data**: `bmad-kb.md`, `publisher-guidelines.md`
|
||||||
|
|
||||||
|
#### Usage Example
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start Book Publisher
|
||||||
|
/BMad:agents:book-publisher
|
||||||
|
|
||||||
|
# Prepare O'Reilly book proposal
|
||||||
|
*prepare-proposal
|
||||||
|
# Agent elicits: publisher (O'Reilly), book details, author bio
|
||||||
|
# Output: book-proposal.md formatted for O'Reilly submission
|
||||||
|
|
||||||
|
# Package manuscript for PacktPub
|
||||||
|
*format-for-packtpub
|
||||||
|
# Agent applies PacktPub style, checks requirements
|
||||||
|
# Output: Formatted manuscript bundle ready for submission
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Integration Patterns
|
||||||
|
|
||||||
|
- **Works with Technical Editor**: Technical Editor polishes content → Book Publisher formats for submission
|
||||||
|
- **Receives from**: All content agents after review and editing phases
|
||||||
|
- **Feeds into**: Publisher-specific submission workflows
|
||||||
|
- **Final agent**: In most workflows (prepares final deliverables)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Specialist Agents
|
||||||
|
|
||||||
|
These agents provide specialized capabilities for specific content types.
|
||||||
|
|
||||||
|
### 📚 API Documenter
|
||||||
|
|
||||||
|
**Agent ID**: `api-documenter`
|
||||||
|
**Title**: Reference Documentation Specialist
|
||||||
|
|
||||||
|
#### Purpose and Role
|
||||||
|
|
||||||
|
Expert in API design patterns, documentation standards, and reference material organization. Creates complete, accurate, and searchable reference documentation that developers trust and rely on.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Generating comprehensive API reference documentation
|
||||||
|
- Documenting functions/methods with parameters and return values
|
||||||
|
- Creating structured parameter/return tables
|
||||||
|
- Writing API usage examples and patterns
|
||||||
|
- Building glossaries and terminology references
|
||||||
|
- Creating reference appendices
|
||||||
|
|
||||||
|
#### Key Commands
|
||||||
|
|
||||||
|
- `*help` - Show numbered list of available commands
|
||||||
|
- `*generate-api-docs` - Runs `generate-api-docs.md` to create comprehensive API reference
|
||||||
|
- `*document-function` - Documents single function with parameters and returns
|
||||||
|
- `*create-reference-table` - Builds structured parameter/return tables
|
||||||
|
- `*write-usage-examples` - Creates code examples showing API usage patterns
|
||||||
|
- `*build-glossary` - Runs `build-glossary.md` to compile terminology reference
|
||||||
|
- `*generate-appendix` - Creates reference appendix using `appendix-tmpl.yaml`
|
||||||
|
- `*exit` - Exits persona
|
||||||
|
|
||||||
|
#### Dependencies
|
||||||
|
|
||||||
|
**Tasks**: `create-doc.md`, `generate-api-docs.md`, `build-glossary.md`, `execute-checklist.md`
|
||||||
|
**Templates**: `api-reference-tmpl.yaml`, `appendix-tmpl.yaml`
|
||||||
|
**Checklists**: `glossary-accuracy-checklist.md`
|
||||||
|
**Data**: `bmad-kb.md`, `code-style-guides.md`, `technical-writing-standards.md`
|
||||||
|
|
||||||
|
#### Usage Example
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start API Documenter
|
||||||
|
/BMad:agents:api-documenter
|
||||||
|
|
||||||
|
# Generate API docs for Python data structures module
|
||||||
|
*generate-api-docs
|
||||||
|
# Agent analyzes module, extracts functions, parameters
|
||||||
|
# Output: api-reference.md with complete function documentation
|
||||||
|
|
||||||
|
# Build glossary for book
|
||||||
|
*build-glossary
|
||||||
|
# Agent compiles terms from chapters
|
||||||
|
# Output: glossary.md with alphabetized terminology
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Integration Patterns
|
||||||
|
|
||||||
|
- **Works with Code Curator**: Code Curator creates examples → API Documenter documents API usage
|
||||||
|
- **Works with Tutorial Architect**: Creates reference docs → Tutorial Architect uses for tutorial content
|
||||||
|
- **Specialist role**: Called when API documentation or glossaries needed
|
||||||
|
- **Feeds into**: Appendix creation, reference section development
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 📸 Screenshot Specialist
|
||||||
|
|
||||||
|
**Agent ID**: `screenshot-specialist`
|
||||||
|
**Title**: Visual Documentation Expert
|
||||||
|
|
||||||
|
#### Purpose and Role
|
||||||
|
|
||||||
|
Expert in technical diagrams, screenshot planning, and visual communication. Creates clear, professional visuals that enhance understanding and meet accessibility standards.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Creating technical diagram specifications (flowcharts, sequence diagrams, architecture diagrams)
|
||||||
|
- Planning screenshot sequences for tutorials
|
||||||
|
- Annotating images with callouts and labels
|
||||||
|
- Optimizing visuals for clarity and appropriate file size
|
||||||
|
- Ensuring accessibility (alt text, color contrast)
|
||||||
|
- Maintaining visual consistency across the book
|
||||||
|
|
||||||
|
#### Key Commands
|
||||||
|
|
||||||
|
- `*help` - Show numbered list of available commands
|
||||||
|
- `*create-diagram-spec` - Runs `create-diagram-spec.md` to design technical diagrams
|
||||||
|
- `*plan-screenshots` - Plans screenshot sequence and identifies key captures
|
||||||
|
- `*annotate-images` - Adds callouts, labels, and highlighting
|
||||||
|
- `*optimize-visuals` - Ensures clarity, file size, and print/web quality
|
||||||
|
- `*exit` - Exits persona
|
||||||
|
|
||||||
|
#### Dependencies
|
||||||
|
|
||||||
|
**Tasks**: `create-doc.md`, `create-diagram-spec.md`, `execute-checklist.md`
|
||||||
|
**Templates**: `diagram-spec-tmpl.yaml`
|
||||||
|
**Checklists**: `diagram-clarity-checklist.md`, `screenshot-quality-checklist.md`
|
||||||
|
**Data**: `bmad-kb.md`, `technical-writing-standards.md`
|
||||||
|
|
||||||
|
#### Usage Example
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start Screenshot Specialist
|
||||||
|
/BMad:agents:screenshot-specialist
|
||||||
|
|
||||||
|
# Create architecture diagram specification
|
||||||
|
*create-diagram-spec
|
||||||
|
# Agent elicits: diagram type, components, relationships
|
||||||
|
# Output: diagram-spec.md with Mermaid code or detailed specification
|
||||||
|
|
||||||
|
# Plan screenshot sequence for tutorial
|
||||||
|
*plan-screenshots
|
||||||
|
# Agent identifies key steps needing screenshots
|
||||||
|
# Output: Screenshot plan with annotations and accessibility notes
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Integration Patterns
|
||||||
|
|
||||||
|
- **Works with Tutorial Architect**: Tutorial Architect identifies visual needs → Screenshot Specialist creates diagrams
|
||||||
|
- **Works with Technical Editor**: Creates visuals → Technical Editor ensures alt text and accessibility
|
||||||
|
- **Specialist role**: Called when visual documentation is needed
|
||||||
|
- **Feeds into**: Chapter assembly, visual asset workflows
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 🏋️ Exercise Creator
|
||||||
|
|
||||||
|
**Agent ID**: `exercise-creator`
|
||||||
|
**Title**: Practice Problem Designer
|
||||||
|
|
||||||
|
#### Purpose and Role
|
||||||
|
|
||||||
|
Expert in exercise design, scaffolding practice, and aligned assessment. Creates exercises that reinforce learning, build confidence, and validate mastery through pedagogically sound practice problems.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Designing practice problem sets aligned with learning objectives
|
||||||
|
- Creating end-of-chapter quizzes and knowledge checks
|
||||||
|
- Writing detailed solutions with explanations
|
||||||
|
- Calibrating exercise difficulty levels
|
||||||
|
- Ensuring variety in exercise types
|
||||||
|
- Aligning exercises with Bloom's taxonomy levels
|
||||||
|
|
||||||
|
#### Key Commands
|
||||||
|
|
||||||
|
- `*help` - Show numbered list of available commands
|
||||||
|
- `*design-exercise-set` - Runs `design-exercises.md` to create practice problems
|
||||||
|
- `*create-quiz` - Designs knowledge check questions for chapter review
|
||||||
|
- `*write-solutions` - Creates detailed solutions with explanations
|
||||||
|
- `*grade-difficulty` - Assesses and calibrates exercise difficulty levels
|
||||||
|
- `*exit` - Exits persona
|
||||||
|
|
||||||
|
#### Dependencies
|
||||||
|
|
||||||
|
**Tasks**: `create-doc.md`, `design-exercises.md`, `execute-checklist.md`
|
||||||
|
**Templates**: `exercise-set-tmpl.yaml`
|
||||||
|
**Checklists**: `exercise-difficulty-checklist.md`, `learning-objectives-checklist.md`
|
||||||
|
**Data**: `bmad-kb.md`, `learning-frameworks.md`
|
||||||
|
|
||||||
|
#### Usage Example
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start Exercise Creator
|
||||||
|
/BMad:agents:exercise-creator
|
||||||
|
|
||||||
|
# Design exercise set for Chapter 4
|
||||||
|
*design-exercise-set
|
||||||
|
# Agent elicits: learning objectives, Bloom's level, difficulty
|
||||||
|
# Output: exercise-set.md with 5-7 problems, solutions, difficulty levels
|
||||||
|
|
||||||
|
# Create quiz questions
|
||||||
|
*create-quiz
|
||||||
|
# Agent creates multiple choice, short answer, coding challenges
|
||||||
|
# Output: Quiz with answer key and explanations
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Integration Patterns
|
||||||
|
|
||||||
|
- **Works with Instructional Designer**: Receives learning objectives → Creates aligned exercises
|
||||||
|
- **Works with Tutorial Architect**: Tutorial teaches concepts → Exercise Creator adds practice
|
||||||
|
- **Works with Code Curator**: Exercise Creator designs coding challenges → Code Curator ensures they work
|
||||||
|
- **Feeds into**: Chapter development, assessment workflows
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Brownfield Agent
|
||||||
|
|
||||||
|
### 📖 Book Analyst
|
||||||
|
|
||||||
|
**Agent ID**: `book-analyst`
|
||||||
|
**Title**: Existing Book Analysis & Revision Planning Specialist
|
||||||
|
|
||||||
|
#### Purpose and Role
|
||||||
|
|
||||||
|
Expert in brownfield book authoring: analyzing existing books, planning 2nd/3rd edition updates, technology version migrations, chapter additions, and systematic incorporation of reviewer feedback while maintaining consistency.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Analyzing existing technical books for revision planning
|
||||||
|
- Planning 2nd/3rd edition updates
|
||||||
|
- Extracting patterns from existing content (style, voice, code conventions)
|
||||||
|
- Assessing impact of technology version changes
|
||||||
|
- Triaging and prioritizing reviewer/publisher feedback
|
||||||
|
- Identifying outdated content and deprecated APIs
|
||||||
|
- Planning chapter additions to existing books
|
||||||
|
|
||||||
|
#### Key Commands
|
||||||
|
|
||||||
|
- `*help` - Show numbered list of available commands
|
||||||
|
- `*analyze-book` - Runs `analyze-existing-book.md` to analyze current book state
|
||||||
|
- `*plan-revision` - Runs `plan-book-revision.md` to create strategic revision plan
|
||||||
|
- `*extract-patterns` - Runs `extract-code-patterns.md` to learn existing code style
|
||||||
|
- `*assess-version-impact` - Analyzes impact of technology version changes
|
||||||
|
- `*triage-feedback` - Categorizes and prioritizes reviewer/publisher feedback
|
||||||
|
- `*identify-outdated-content` - Scans for deprecated APIs and breaking changes
|
||||||
|
- `*exit` - Exits persona
|
||||||
|
|
||||||
|
#### Dependencies
|
||||||
|
|
||||||
|
**Tasks**: `create-doc.md`, `analyze-existing-book.md`, `plan-book-revision.md`, `extract-code-patterns.md`, `incorporate-reviewer-feedback.md`, `execute-checklist.md`
|
||||||
|
**Templates**: `book-analysis-report-tmpl.yaml`, `revision-plan-tmpl.yaml`
|
||||||
|
**Checklists**: `version-update-checklist.md`, `revision-completeness-checklist.md`, `existing-book-integration-checklist.md`
|
||||||
|
**Data**: `bmad-kb.md`, `learning-frameworks.md`
|
||||||
|
|
||||||
|
#### Usage Example
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start Book Analyst
|
||||||
|
/BMad:agents:book-analyst
|
||||||
|
|
||||||
|
# Analyze existing book for 2nd edition planning
|
||||||
|
*analyze-book
|
||||||
|
# Agent reads entire book, extracts patterns, identifies issues
|
||||||
|
# Output: book-analysis-report.md with structure, patterns, outdated content
|
||||||
|
|
||||||
|
# Plan revision for Python 3.10 → 3.12 migration
|
||||||
|
*assess-version-impact
|
||||||
|
# Agent identifies breaking changes, deprecated features
|
||||||
|
# Output: version-impact-assessment.md with migration plan
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Integration Patterns
|
||||||
|
|
||||||
|
- **Initiates brownfield workflows**: Analyzes existing content → Provides context to other agents
|
||||||
|
- **Works with all agents**: Provides pattern extraction and consistency guidelines
|
||||||
|
- **Feeds into**: Revision planning workflows, version update workflows
|
||||||
|
- **Coordinates**: Book edition updates, chapter additions to existing books
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Optional Agents
|
||||||
|
|
||||||
|
These agents provide advanced capabilities for complex scenarios. They can be merged with other agents for simpler deployments.
|
||||||
|
|
||||||
|
### 🗺️ Learning Path Designer
|
||||||
|
|
||||||
|
**Agent ID**: `learning-path-designer`
|
||||||
|
**Title**: Prerequisite Mapping & Skill Progression Specialist
|
||||||
|
|
||||||
|
#### Purpose and Role
|
||||||
|
|
||||||
|
Expert in cognitive scaffolding and prerequisite mapping. Designs learning journeys where readers can successfully navigate without encountering unexplained concepts or prerequisite violations.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Designing learning progressions and skill trees
|
||||||
|
- Mapping chapter-to-chapter prerequisite dependencies
|
||||||
|
- Creating visual skill scaffolding diagrams
|
||||||
|
- Assessing reader readiness at chapter transitions
|
||||||
|
- Validating learning flow for knowledge gaps
|
||||||
|
- Identifying missing foundational topics
|
||||||
|
- Distinguishing optional vs. required chapters
|
||||||
|
|
||||||
|
#### Key Commands
|
||||||
|
|
||||||
|
- `*help` - Show numbered list of available commands
|
||||||
|
- `*map-prerequisites` - Runs `design-learning-path.md` to map chapter dependencies
|
||||||
|
- `*design-skill-tree` - Creates skill progression tree showing knowledge building
|
||||||
|
- `*assess-readiness` - Evaluates reader readiness at specific chapter points
|
||||||
|
- `*validate-learning-flow` - Checks for knowledge gaps and prerequisite violations
|
||||||
|
- `*identify-gaps` - Finds missing foundational topics or unexplained concepts
|
||||||
|
- `*exit` - Exits persona
|
||||||
|
|
||||||
|
#### Dependencies
|
||||||
|
|
||||||
|
**Tasks**: `design-learning-path.md`, `execute-checklist.md`
|
||||||
|
**Templates**: `learning-objectives-tmpl.yaml`, `book-outline-tmpl.yaml`
|
||||||
|
**Checklists**: `learning-objectives-checklist.md`, `prerequisite-clarity-checklist.md`
|
||||||
|
**Data**: `bmad-kb.md`, `learning-frameworks.md`
|
||||||
|
|
||||||
|
**Note**: Can be merged with Instructional Designer for simpler deployments. Use this specialist when dealing with complex, multi-level technical topics requiring careful prerequisite analysis.
|
||||||
|
|
||||||
|
#### Usage Example
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start Learning Path Designer
|
||||||
|
/BMad:agents:learning-path-designer
|
||||||
|
|
||||||
|
# Map prerequisites for entire book
|
||||||
|
*map-prerequisites
|
||||||
|
# Agent analyzes chapters, identifies dependencies
|
||||||
|
# Output: learning-path.md with dependency graph, skill tree
|
||||||
|
|
||||||
|
# Validate learning flow
|
||||||
|
*validate-learning-flow
|
||||||
|
# Agent checks for knowledge gaps, prerequisite violations
|
||||||
|
# Output: Validation report with identified gaps and recommendations
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Integration Patterns
|
||||||
|
|
||||||
|
- **Works with Instructional Designer**: Collaborates on learning objectives and progression
|
||||||
|
- **Optional enhancement**: Provides deeper prerequisite analysis than Instructional Designer alone
|
||||||
|
- **Complex books**: Most useful for multi-level technical topics
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 🔧 Sample Code Maintainer
|
||||||
|
|
||||||
|
**Agent ID**: `sample-code-maintainer`
|
||||||
|
**Title**: Code Repository Management & CI/CD Specialist
|
||||||
|
|
||||||
|
#### Purpose and Role
|
||||||
|
|
||||||
|
DevOps-minded specialist in code repository management and automation. Creates and maintains code repositories that readers can clone, install, and use immediately without frustration.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Setting up code repository structure and organization
|
||||||
|
- Managing dependencies and version pinning
|
||||||
|
- Creating CI/CD pipelines (GitHub Actions, etc.)
|
||||||
|
- Automating testing across all code examples
|
||||||
|
- Publishing repositories for public release
|
||||||
|
- Maintaining long-term repository health
|
||||||
|
|
||||||
|
#### Key Commands
|
||||||
|
|
||||||
|
- `*help` - Show numbered list of available commands
|
||||||
|
- `*organize-code-repo` - Runs `setup-code-repository.md` to create repository structure
|
||||||
|
- `*update-dependencies` - Updates package dependencies and tests compatibility
|
||||||
|
- `*create-ci-pipeline` - Sets up GitHub Actions or other CI/CD automation
|
||||||
|
- `*run-tests` - Executes `test-code-examples.md` across all examples
|
||||||
|
- `*publish-repo` - Prepares repository for public release
|
||||||
|
- `*exit` - Exits persona
|
||||||
|
|
||||||
|
#### Dependencies
|
||||||
|
|
||||||
|
**Tasks**: `setup-code-repository.md`, `test-code-examples.md`, `execute-checklist.md`
|
||||||
|
**Checklists**: `code-testing-checklist.md`, `repository-quality-checklist.md`, `version-compatibility-checklist.md`
|
||||||
|
**Data**: `bmad-kb.md`
|
||||||
|
|
||||||
|
**Note**: Can be merged with Code Curator for simpler deployments. Use this specialist when managing large code repositories with complex dependencies and CI/CD requirements.
|
||||||
|
|
||||||
|
#### Usage Example
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start Sample Code Maintainer
|
||||||
|
/BMad:agents:sample-code-maintainer
|
||||||
|
|
||||||
|
# Set up repository for book code
|
||||||
|
*organize-code-repo
|
||||||
|
# Agent creates chapter folders, README, dependencies
|
||||||
|
# Output: Well-organized repository structure
|
||||||
|
|
||||||
|
# Create GitHub Actions CI pipeline
|
||||||
|
*create-ci-pipeline
|
||||||
|
# Agent creates workflow YAML for automated testing
|
||||||
|
# Output: .github/workflows/test.yml with matrix testing
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Integration Patterns
|
||||||
|
|
||||||
|
- **Works with Code Curator**: Code Curator creates examples → Sample Code Maintainer organizes and automates
|
||||||
|
- **Optional enhancement**: Provides repository management and CI/CD beyond Code Curator's scope
|
||||||
|
- **Large codebases**: Most useful for books with extensive code examples
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 🔢 Version Manager
|
||||||
|
|
||||||
|
**Agent ID**: `version-manager`
|
||||||
|
**Title**: Multi-Version & Platform Support Specialist
|
||||||
|
|
||||||
|
#### Purpose and Role
|
||||||
|
|
||||||
|
Expert in multi-version compatibility and cross-platform support. Ensures code examples work correctly across entire version matrix and that readers know exactly which versions are supported.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Managing multi-version compatibility testing
|
||||||
|
- Documenting platform-specific code differences
|
||||||
|
- Creating version testing matrices
|
||||||
|
- Testing code across all versions and platforms
|
||||||
|
- Adapting code examples for specific version requirements
|
||||||
|
- Documenting breaking changes between versions
|
||||||
|
|
||||||
|
#### Key Commands
|
||||||
|
|
||||||
|
- `*help` - Show numbered list of available commands
|
||||||
|
- `*create-version-matrix` - Runs `version-matrix-check.md` to define version testing scope
|
||||||
|
- `*adapt-for-version` - Modifies code examples for specific version compatibility
|
||||||
|
- `*platform-variations` - Documents platform-specific code differences
|
||||||
|
- `*test-matrix` - Executes tests across all versions and platforms in matrix
|
||||||
|
- `*exit` - Exits persona
|
||||||
|
|
||||||
|
#### Dependencies
|
||||||
|
|
||||||
|
**Tasks**: `version-matrix-check.md`, `execute-checklist.md`
|
||||||
|
**Checklists**: `version-compatibility-checklist.md`, `cross-platform-checklist.md`
|
||||||
|
**Data**: `bmad-kb.md`, `code-style-guides.md`
|
||||||
|
|
||||||
|
**Note**: Can be merged with Code Curator for simpler deployments. Use this specialist when writing books covering multiple versions or platforms with significant compatibility differences.
|
||||||
|
|
||||||
|
#### Usage Example
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start Version Manager
|
||||||
|
/BMad:agents:version-manager
|
||||||
|
|
||||||
|
# Create version testing matrix
|
||||||
|
*create-version-matrix
|
||||||
|
# Agent elicits: languages, versions, platforms
|
||||||
|
# Output: version-matrix.yaml with testing scope (e.g., Python 3.10, 3.11, 3.12)
|
||||||
|
|
||||||
|
# Test across matrix
|
||||||
|
*test-matrix
|
||||||
|
# Agent runs tests on all version/platform combinations
|
||||||
|
# Output: Matrix test results with pass/fail for each combination
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Integration Patterns
|
||||||
|
|
||||||
|
- **Works with Code Curator**: Collaborates on multi-version testing and compatibility
|
||||||
|
- **Optional enhancement**: Provides explicit version management beyond Code Curator's testing
|
||||||
|
- **Multi-version books**: Most useful when covering Python 3.10+3.11+3.12 or Node 18+20+22, etc.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Agent Comparison Table
|
||||||
|
|
||||||
|
| Agent | Category | Icon | Primary Focus | When to Use |
|
||||||
|
|-------|----------|------|---------------|-------------|
|
||||||
|
| Instructional Designer | Core Planning | 🎓 | Learning architecture, pedagogical structure | Book outlines, learning objectives, scaffolding |
|
||||||
|
| Tutorial Architect | Core Planning | 📝 | Hands-on tutorials, step-by-step instruction | Tutorial design, chapter outlines, walkthroughs |
|
||||||
|
| Code Curator | Core Planning | 💻 | Code quality, testing, best practices | Code examples, testing, version compatibility |
|
||||||
|
| Technical Reviewer | Core Review | 🔍 | Technical accuracy, security, validation | Chapter reviews, accuracy checks, security audits |
|
||||||
|
| Technical Editor | Core Review | ✍️ | Clarity, consistency, publisher compliance | Copy editing, style checks, publication prep |
|
||||||
|
| Book Publisher | Core Publishing | 📦 | Manuscript packaging, submission prep | Publisher proposals, manuscript formatting |
|
||||||
|
| API Documenter | Specialist | 📚 | API reference, glossaries, appendices | API docs, reference tables, glossaries |
|
||||||
|
| Screenshot Specialist | Specialist | 📸 | Diagrams, screenshots, visual documentation | Technical diagrams, screenshot planning |
|
||||||
|
| Exercise Creator | Specialist | 🏋️ | Practice problems, assessments, quizzes | Exercise sets, quizzes, solutions |
|
||||||
|
| Book Analyst | Brownfield | 📖 | Existing book analysis, revision planning | 2nd editions, version migrations, updates |
|
||||||
|
| Learning Path Designer | Optional | 🗺️ | Prerequisite mapping, skill progression | Complex skill trees, prerequisite validation |
|
||||||
|
| Sample Code Maintainer | Optional | 🔧 | Repository management, CI/CD | Large codebases, automated testing |
|
||||||
|
| Version Manager | Optional | 🔢 | Multi-version compatibility, platforms | Multi-version testing, platform differences |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Agent Selection Decision Tree
|
||||||
|
|
||||||
|
**I want to...**
|
||||||
|
|
||||||
|
### Plan a new book
|
||||||
|
→ Start with **Instructional Designer** (`*create-book-outline`)
|
||||||
|
→ Then **Tutorial Architect** for chapter-level structure
|
||||||
|
→ Consider **Learning Path Designer** for complex prerequisite mapping
|
||||||
|
|
||||||
|
### Create tutorial content
|
||||||
|
→ Use **Tutorial Architect** (`*create-tutorial`, `*write-walkthrough`)
|
||||||
|
→ Collaborate with **Code Curator** for tested code examples
|
||||||
|
→ Add **Exercise Creator** for practice problems
|
||||||
|
|
||||||
|
### Ensure code quality
|
||||||
|
→ Use **Code Curator** (`*create-code-example`, `*test-all-examples`)
|
||||||
|
→ Add **Sample Code Maintainer** for large repositories with CI/CD
|
||||||
|
→ Add **Version Manager** for multi-version compatibility
|
||||||
|
|
||||||
|
### Review and refine content
|
||||||
|
→ Use **Technical Reviewer** first (`*review-chapter` for accuracy)
|
||||||
|
→ Then **Technical Editor** (`*edit-chapter` for clarity and style)
|
||||||
|
→ Finish with **Book Publisher** for submission formatting
|
||||||
|
|
||||||
|
### Create specialized content
|
||||||
|
→ **API Documenter** for API reference sections
|
||||||
|
→ **Screenshot Specialist** for diagrams and visuals
|
||||||
|
→ **Exercise Creator** for practice problem sets
|
||||||
|
|
||||||
|
### Update existing book
|
||||||
|
→ Start with **Book Analyst** (`*analyze-book`, `*plan-revision`)
|
||||||
|
→ Then coordinate other agents based on revision needs
|
||||||
|
→ Use **Version Manager** for version migration
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Common Agent Workflows
|
||||||
|
|
||||||
|
### Greenfield Book (New Book from Scratch)
|
||||||
|
|
||||||
|
1. **Instructional Designer** - Create book outline with learning objectives
|
||||||
|
2. **Tutorial Architect** - Design chapter outlines with tutorial structure
|
||||||
|
3. **Code Curator** - Develop and test all code examples
|
||||||
|
4. **Exercise Creator** - Create practice problems and quizzes
|
||||||
|
5. **Technical Reviewer** - Validate technical accuracy
|
||||||
|
6. **Technical Editor** - Polish clarity and consistency
|
||||||
|
7. **Book Publisher** - Format and submit to publisher
|
||||||
|
|
||||||
|
### Section-Driven Development
|
||||||
|
|
||||||
|
1. **Tutorial Architect** - Outline section with tutorial steps
|
||||||
|
2. **Code Curator** - Create tested code examples for section
|
||||||
|
3. **Screenshot Specialist** - Design diagrams and visuals (if needed)
|
||||||
|
4. **Technical Reviewer** - Review section for accuracy
|
||||||
|
5. **Technical Editor** - Edit section for clarity
|
||||||
|
6. Repeat for next section
|
||||||
|
|
||||||
|
### Brownfield Book (2nd Edition Update)
|
||||||
|
|
||||||
|
1. **Book Analyst** - Analyze existing book, extract patterns
|
||||||
|
2. **Book Analyst** - Assess version impact, plan revision
|
||||||
|
3. **Version Manager** - Test code examples on new versions
|
||||||
|
4. **Code Curator** - Update failing code examples
|
||||||
|
5. **Technical Reviewer** - Review updated content
|
||||||
|
6. **Technical Editor** - Ensure consistency with existing style
|
||||||
|
7. **Book Publisher** - Reformat for submission
|
||||||
|
|
||||||
|
### API Reference Book
|
||||||
|
|
||||||
|
1. **Instructional Designer** - Structure book around API concepts
|
||||||
|
2. **API Documenter** - Generate comprehensive API documentation
|
||||||
|
3. **Code Curator** - Create usage examples for each API
|
||||||
|
4. **Tutorial Architect** - Create walkthroughs for common patterns
|
||||||
|
5. **Technical Reviewer** - Validate API accuracy
|
||||||
|
6. **Technical Editor** - Polish reference documentation
|
||||||
|
7. **Book Publisher** - Format for publication
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Integration Best Practices
|
||||||
|
|
||||||
|
### Agent Coordination Principles
|
||||||
|
|
||||||
|
1. **Sequential workflows**: Planning agents → Content agents → Review agents → Publishing agent
|
||||||
|
2. **Parallel collaboration**: Code Curator + Screenshot Specialist can work simultaneously on same chapter
|
||||||
|
3. **Iteration cycles**: Technical Reviewer → Author revisions → Technical Editor → Final review
|
||||||
|
4. **Specialist inclusion**: Add API Documenter, Screenshot Specialist, Exercise Creator as needed
|
||||||
|
|
||||||
|
### Dependency Sharing
|
||||||
|
|
||||||
|
Multiple agents share common dependencies:
|
||||||
|
- **All agents**: Use `create-doc.md`, `execute-checklist.md`, `bmad-kb.md`
|
||||||
|
- **Planning agents**: Share `learning-frameworks.md`, `book-structures.md`
|
||||||
|
- **Code agents**: Share `code-style-guides.md`
|
||||||
|
- **Review/Publishing agents**: Share `technical-writing-standards.md`, `publisher-guidelines.md`
|
||||||
|
|
||||||
|
### When to Use Optional Agents
|
||||||
|
|
||||||
|
- **Learning Path Designer**: Complex books with deep prerequisite dependencies (e.g., advanced algorithms, distributed systems)
|
||||||
|
- **Sample Code Maintainer**: Books with 50+ code examples, complex build systems, or CI/CD requirements
|
||||||
|
- **Version Manager**: Books covering Python 3.10/3.11/3.12 or Node 18/20/22 with breaking changes
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Conclusion
|
||||||
|
|
||||||
|
The BMad Technical Writing Expansion Pack's **13 specialized agents** provide comprehensive coverage of the entire technical book authoring lifecycle. By understanding each agent's purpose, commands, and integration patterns, you can:
|
||||||
|
|
||||||
|
- **Plan effectively** using Core Planning Agents
|
||||||
|
- **Ensure quality** through Core Review Agents
|
||||||
|
- **Prepare for publication** with the Core Publishing Agent
|
||||||
|
- **Handle specialized content** with Specialist Agents
|
||||||
|
- **Update existing books** using the Brownfield Agent
|
||||||
|
- **Address complex scenarios** with Optional Agents
|
||||||
|
|
||||||
|
Choose agents based on your workflow needs, and combine them strategically to create high-quality technical books efficiently.
|
||||||
|
|
||||||
|
**Total agent count**: 13
|
||||||
|
**Word count**: ~5,100 words
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Related Documentation**:
|
||||||
|
- [Workflow Guide](workflow-guide.md) - Detailed workflows using these agents
|
||||||
|
- [Template Gallery](template-gallery.md) - Templates used by agent dependencies
|
||||||
|
- [Task Reference](task-reference.md) - Tasks executed by agent commands
|
||||||
|
- [User Guide](user-guide.md) - Conceptual overview of the framework
|
||||||
|
|
@ -0,0 +1,843 @@
|
||||||
|
# Checklist Reference
|
||||||
|
|
||||||
|
## Introduction
|
||||||
|
|
||||||
|
The BMad Technical Writing Expansion Pack provides **31 quality assurance checklists** that serve as validation gates throughout the book authoring lifecycle. Each checklist defines specific criteria that must be met before proceeding to the next phase.
|
||||||
|
|
||||||
|
This comprehensive reference documents all 31 checklists organized by phase, with:
|
||||||
|
|
||||||
|
- **Checklist name and purpose** - What it validates
|
||||||
|
- **When to use** - Quality gate timing
|
||||||
|
- **Key criteria** - Most important validation points
|
||||||
|
- **Pass criteria** - What constitutes passing
|
||||||
|
- **Related workflows** - Which workflows use this checklist
|
||||||
|
- **Related agents** - Which agents execute this checklist
|
||||||
|
|
||||||
|
### Checklist Categories
|
||||||
|
|
||||||
|
- **Planning Phase (2 checklists)**: Learning objectives, prerequisites
|
||||||
|
- **Drafting Phase (5 checklists)**: Chapter completeness, book proposals, tutorials
|
||||||
|
- **Code Quality (5 checklists)**: Code quality, testing, security, version compatibility, performance
|
||||||
|
- **Review Phase (4 checklists)**: Technical accuracy, readability, accessibility, inclusive language
|
||||||
|
- **Publishing Phase (7 checklists)**: Publisher-specific formats, final manuscript, MEAP, self-publishing
|
||||||
|
- **Final QA (8 checklists)**: Diagrams, screenshots, glossaries, indexes, citations, revisions, repositories, cross-platform
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Planning Phase Checklists
|
||||||
|
|
||||||
|
### learning-objectives-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Validates learning objectives are measurable and aligned with Bloom's taxonomy
|
||||||
|
|
||||||
|
**When to Use**: After defining learning objectives for chapter or book
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- Learning objectives use action verbs (implement, analyze, create, evaluate)
|
||||||
|
- Objectives are specific and measurable
|
||||||
|
- Aligned with book-level learning path
|
||||||
|
- Appropriate for target audience skill level
|
||||||
|
- 3-5 objectives per chapter (not too few, not too many)
|
||||||
|
- Each objective maps to specific exercises or assessments
|
||||||
|
|
||||||
|
**Pass Criteria**: All objectives are measurable, actionable, and properly scoped
|
||||||
|
|
||||||
|
**Related Workflows**: Book Planning, Chapter Development, Tutorial Creation
|
||||||
|
**Related Agents**: instructional-designer, learning-path-designer, exercise-creator
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### prerequisite-clarity-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Ensures prerequisites are clearly stated and achievable
|
||||||
|
|
||||||
|
**When to Use**: After defining chapter prerequisites or book prerequisites
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- Prerequisites explicitly listed (no assumptions)
|
||||||
|
- Software/tool versions specified (e.g., "Python 3.11+")
|
||||||
|
- Prior chapters required are identified
|
||||||
|
- External knowledge assumptions stated
|
||||||
|
- Setup time estimated
|
||||||
|
- Prerequisites are achievable for target audience
|
||||||
|
|
||||||
|
**Pass Criteria**: Reader can verify they meet all prerequisites before starting
|
||||||
|
|
||||||
|
**Related Workflows**: Book Planning, Chapter Development
|
||||||
|
**Related Agents**: instructional-designer, tutorial-architect
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Drafting Phase Checklists
|
||||||
|
|
||||||
|
### chapter-completeness-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Validates chapter has all required components before publication
|
||||||
|
|
||||||
|
**When to Use**: Final validation before marking chapter "Ready for Publication"
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- All learning objectives addressed
|
||||||
|
- Introduction hooks reader and previews content
|
||||||
|
- All sections from outline present
|
||||||
|
- Code examples inline and explained
|
||||||
|
- Exercises included with difficulty progression
|
||||||
|
- Summary recaps key concepts
|
||||||
|
- Transitions to next chapter clear
|
||||||
|
- 3-5 diagrams/screenshots included (if applicable)
|
||||||
|
- Cross-references validated
|
||||||
|
- File list updated with all code files
|
||||||
|
|
||||||
|
**Pass Criteria**: Chapter meets all structural and content requirements
|
||||||
|
|
||||||
|
**Related Workflows**: Chapter Development, Chapter Assembly
|
||||||
|
**Related Agents**: tutorial-architect
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### book-proposal-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Validates book proposal is complete and compelling for publishers
|
||||||
|
|
||||||
|
**When to Use**: Before submitting proposal to publisher
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- Market analysis included (target audience, market size)
|
||||||
|
- Competitive titles identified (3-5 books)
|
||||||
|
- Unique value proposition clearly stated
|
||||||
|
- High-level chapter list (10-15 chapters typical)
|
||||||
|
- Author platform described (credentials, audience)
|
||||||
|
- Realistic timeline (12-18 months typical)
|
||||||
|
- Technical stack and versions specified
|
||||||
|
- Sample chapter or outline included
|
||||||
|
|
||||||
|
**Pass Criteria**: Proposal ready for publisher submission
|
||||||
|
|
||||||
|
**Related Workflows**: Book Planning
|
||||||
|
**Related Agents**: book-publisher
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### tutorial-effectiveness-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Validates tutorials are clear, tested, and student-friendly
|
||||||
|
|
||||||
|
**When to Use**: After writing tutorial, before integration into chapter
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- ONE clear learning objective stated
|
||||||
|
- Prerequisites explicitly listed
|
||||||
|
- 8-15 step-by-step instructions
|
||||||
|
- Each step has expected output documented
|
||||||
|
- Troubleshooting section included
|
||||||
|
- Tested in fresh environment
|
||||||
|
- Realistic time estimate (add 50-100% buffer for students)
|
||||||
|
- Success criteria verifiable at end
|
||||||
|
- Code copy-paste ready but encourages understanding
|
||||||
|
|
||||||
|
**Pass Criteria**: Tutorial tested successfully by someone following instructions exactly
|
||||||
|
|
||||||
|
**Related Workflows**: Tutorial Creation, Chapter Development
|
||||||
|
**Related Agents**: tutorial-architect, code-curator
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### readability-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Ensures content is clear, accessible, and professional
|
||||||
|
|
||||||
|
**When to Use**: During copy editing phase
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- Sentences are concise (20-25 words average)
|
||||||
|
- Paragraphs are scannable (3-5 sentences)
|
||||||
|
- Active voice used primarily
|
||||||
|
- Technical jargon defined on first use
|
||||||
|
- Transitions smooth between sections
|
||||||
|
- Consistent terminology throughout
|
||||||
|
- Code examples have clear context
|
||||||
|
- Headings are descriptive and hierarchical
|
||||||
|
|
||||||
|
**Pass Criteria**: Content reads clearly at target audience reading level
|
||||||
|
|
||||||
|
**Related Agents**: technical-editor
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### exercise-difficulty-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Validates exercise difficulty progression and alignment
|
||||||
|
|
||||||
|
**When to Use**: After creating exercise sets
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- Exercises aligned with learning objectives
|
||||||
|
- Difficulty progression (easy → medium → challenging)
|
||||||
|
- Mix of exercise types (guided, independent, challenges)
|
||||||
|
- Clear success criteria for each exercise
|
||||||
|
- Hints provided for challenging exercises
|
||||||
|
- Solutions available (or "hints only" if pedagogically appropriate)
|
||||||
|
- Time estimates realistic
|
||||||
|
|
||||||
|
**Pass Criteria**: Exercises build confidence and validate learning
|
||||||
|
|
||||||
|
**Related Agents**: exercise-creator
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Code Quality Checklists
|
||||||
|
|
||||||
|
### code-quality-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Validates code examples follow best practices and style guides
|
||||||
|
|
||||||
|
**When to Use**: After developing code examples, before integration
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- Code follows language style guide (PEP 8, Airbnb JS, etc.)
|
||||||
|
- Variable and function names are descriptive
|
||||||
|
- Functions are appropriately sized (<50 lines typical)
|
||||||
|
- No code duplication (DRY principle)
|
||||||
|
- Comments explain "why" not "what"
|
||||||
|
- Error handling demonstrated
|
||||||
|
- Complexity reasonable for learning example
|
||||||
|
- Code is idiomatic (uses language features appropriately)
|
||||||
|
|
||||||
|
**Pass Criteria**: Code demonstrates best practices
|
||||||
|
|
||||||
|
**Related Workflows**: Code Example Workflow
|
||||||
|
**Related Agents**: code-curator
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### code-testing-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Ensures all code examples are thoroughly tested
|
||||||
|
|
||||||
|
**When to Use**: After writing code, before marking example complete
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- Code runs on target version (e.g., Python 3.11+)
|
||||||
|
- Edge cases tested
|
||||||
|
- Error conditions handled and tested
|
||||||
|
- Dependencies install cleanly
|
||||||
|
- Tests pass in fresh environment
|
||||||
|
- Test coverage adequate for example
|
||||||
|
- Output matches documented expectations
|
||||||
|
- Performance acceptable (if relevant)
|
||||||
|
|
||||||
|
**Pass Criteria**: All tests pass in clean environment
|
||||||
|
|
||||||
|
**Related Workflows**: Code Example Workflow, Section Development
|
||||||
|
**Related Agents**: code-curator, sample-code-maintainer
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### security-best-practices-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Validates code examples follow secure coding practices
|
||||||
|
|
||||||
|
**When to Use**: Security review during code development
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- No hardcoded secrets or credentials
|
||||||
|
- Input validation present where needed
|
||||||
|
- No SQL injection vulnerabilities
|
||||||
|
- No XSS vulnerabilities (web examples)
|
||||||
|
- Dependencies have no known CVEs
|
||||||
|
- Authentication/authorization demonstrated correctly
|
||||||
|
- HTTPS used (not HTTP) for web examples
|
||||||
|
- Error messages don't leak sensitive info
|
||||||
|
|
||||||
|
**Pass Criteria**: No security vulnerabilities identified
|
||||||
|
|
||||||
|
**Related Workflows**: Code Example Workflow, Technical Review
|
||||||
|
**Related Agents**: code-curator, technical-reviewer
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### version-compatibility-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Ensures code works across specified versions
|
||||||
|
|
||||||
|
**When to Use**: Multi-version testing (e.g., Python 3.10, 3.11, 3.12)
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- Code tested on all specified versions
|
||||||
|
- Breaking changes documented
|
||||||
|
- Version-specific workarounds provided if needed
|
||||||
|
- Dependencies compatible across versions
|
||||||
|
- Clear version requirements stated
|
||||||
|
- Deprecated features avoided (or flagged)
|
||||||
|
- Future-proofing considered
|
||||||
|
|
||||||
|
**Pass Criteria**: Code works on all specified versions
|
||||||
|
|
||||||
|
**Related Workflows**: Code Example Workflow, Book Edition Update
|
||||||
|
**Related Agents**: version-manager, code-curator
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### performance-considerations-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Validates performance implications are addressed
|
||||||
|
|
||||||
|
**When to Use**: Technical review phase, especially for performance-critical examples
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- Time complexity stated (Big-O notation)
|
||||||
|
- Space complexity stated where relevant
|
||||||
|
- Performance characteristics explained
|
||||||
|
- Optimization trade-offs discussed
|
||||||
|
- Scalability considerations addressed
|
||||||
|
- Benchmarks provided for performance-critical code
|
||||||
|
- Alternative approaches mentioned when relevant
|
||||||
|
|
||||||
|
**Pass Criteria**: Performance implications clearly explained
|
||||||
|
|
||||||
|
**Related Workflows**: Technical Review
|
||||||
|
**Related Agents**: technical-reviewer
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Review Phase Checklists
|
||||||
|
|
||||||
|
### technical-accuracy-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Validates technical correctness of content
|
||||||
|
|
||||||
|
**When to Use**: Technical review phase (primary quality gate)
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- All technical claims verified against official documentation
|
||||||
|
- Code examples execute correctly
|
||||||
|
- No technical errors or misconceptions
|
||||||
|
- API usage follows current best practices
|
||||||
|
- Information is current (not outdated or deprecated)
|
||||||
|
- Facts are verifiable
|
||||||
|
- Links to official documentation provided
|
||||||
|
- Edge cases and limitations discussed
|
||||||
|
|
||||||
|
**Pass Criteria**: No critical technical errors identified
|
||||||
|
|
||||||
|
**Related Workflows**: Technical Review, Chapter Assembly
|
||||||
|
**Related Agents**: technical-reviewer
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### accessibility-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Ensures content is accessible to all readers
|
||||||
|
|
||||||
|
**When to Use**: Editorial review and final manuscript review
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- All images have descriptive alt text
|
||||||
|
- Color is not sole means of conveying information
|
||||||
|
- Code snippets have sufficient contrast
|
||||||
|
- Screen reader friendly formatting
|
||||||
|
- Inclusive examples (diverse names, scenarios)
|
||||||
|
- Clear heading hierarchy
|
||||||
|
- Abbreviations defined on first use
|
||||||
|
- Tables have header rows
|
||||||
|
|
||||||
|
**Pass Criteria**: Content meets accessibility standards (WCAG 2.1 AA)
|
||||||
|
|
||||||
|
**Related Workflows**: Technical Editor review, Final manuscript
|
||||||
|
**Related Agents**: technical-editor
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### inclusive-language-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Validates use of inclusive, bias-free language
|
||||||
|
|
||||||
|
**When to Use**: Editorial review phase
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- Gender-neutral language used (they/them instead of he/she)
|
||||||
|
- Diverse examples and scenarios
|
||||||
|
- Avoids ableist language
|
||||||
|
- Culturally sensitive terminology
|
||||||
|
- Avoids assumptions about reader background
|
||||||
|
- Inclusive character names in examples
|
||||||
|
- Welcoming tone for all skill levels
|
||||||
|
|
||||||
|
**Pass Criteria**: Content uses inclusive language throughout
|
||||||
|
|
||||||
|
**Related Agents**: technical-editor
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### citation-accuracy-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Validates all citations, references, and attributions
|
||||||
|
|
||||||
|
**When to Use**: Final review before publication
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- All external sources properly cited
|
||||||
|
- Code adapted from others has attribution
|
||||||
|
- Quotes have sources
|
||||||
|
- Links to original sources provided
|
||||||
|
- Copyright permissions obtained for images
|
||||||
|
- License compliance for code examples
|
||||||
|
- Bibliography/references section complete
|
||||||
|
|
||||||
|
**Pass Criteria**: All sources properly attributed
|
||||||
|
|
||||||
|
**Related Agents**: technical-editor
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Publishing Phase Checklists
|
||||||
|
|
||||||
|
### packtpub-submission-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Validates manuscript meets PacktPub requirements
|
||||||
|
|
||||||
|
**When to Use**: Before submitting to PacktPub
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- Word format (.docx) or requested format
|
||||||
|
- Chapter count matches proposal
|
||||||
|
- PacktPub style guide followed
|
||||||
|
- Code repository URL provided
|
||||||
|
- Author bio and headshot included
|
||||||
|
- Sample chapters polished
|
||||||
|
- Technical depth appropriate for PacktPub audience
|
||||||
|
- Consistent formatting throughout
|
||||||
|
|
||||||
|
**Pass Criteria**: Manuscript ready for PacktPub submission
|
||||||
|
|
||||||
|
**Related Workflows**: PacktPub Submission
|
||||||
|
**Related Agents**: book-publisher, technical-editor
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### oreilly-format-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Validates manuscript meets O'Reilly Atlas requirements
|
||||||
|
|
||||||
|
**When to Use**: Before submitting to O'Reilly
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- AsciiDoc format (or Markdown if permitted)
|
||||||
|
- Chicago Manual of Style followed
|
||||||
|
- Atlas repository structure correct
|
||||||
|
- Code repository linked correctly
|
||||||
|
- Technical examples follow O'Reilly standards
|
||||||
|
- Callouts formatted correctly (notes, warnings, tips)
|
||||||
|
- Cross-references use correct syntax
|
||||||
|
- Images at appropriate resolution (300 DPI for print)
|
||||||
|
|
||||||
|
**Pass Criteria**: Manuscript ready for O'Reilly Atlas
|
||||||
|
|
||||||
|
**Related Workflows**: O'Reilly Submission
|
||||||
|
**Related Agents**: book-publisher, technical-editor
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### manning-meap-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Validates chapter ready for Manning Early Access Program
|
||||||
|
|
||||||
|
**When to Use**: Before each MEAP chapter release
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- Manning style guide followed
|
||||||
|
- Chapter technically complete
|
||||||
|
- Code tested and working
|
||||||
|
- Exercises included
|
||||||
|
- MEAP-specific formatting applied
|
||||||
|
- Revision history noted (for updated chapters)
|
||||||
|
- Chapter stands alone if needed (context provided)
|
||||||
|
|
||||||
|
**Pass Criteria**: Chapter ready for Manning MEAP release
|
||||||
|
|
||||||
|
**Related Workflows**: Manning MEAP
|
||||||
|
**Related Agents**: book-publisher
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### meap-readiness-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: General early access program readiness (any publisher)
|
||||||
|
|
||||||
|
**When to Use**: Before releasing chapters incrementally
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- Chapter is self-contained
|
||||||
|
- Code repository accessible
|
||||||
|
- Known issues documented
|
||||||
|
- Feedback mechanism clear
|
||||||
|
- Version/date stamped
|
||||||
|
- Revision plan for feedback incorporation
|
||||||
|
|
||||||
|
**Pass Criteria**: Chapter ready for early access readers
|
||||||
|
|
||||||
|
**Related Agents**: book-publisher
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### self-publishing-standards-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Validates self-published book meets professional standards
|
||||||
|
|
||||||
|
**When to Use**: Before self-publishing release
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- Professional cover design
|
||||||
|
- ISBN obtained (if applicable)
|
||||||
|
- Copyright page complete
|
||||||
|
- Table of contents functional (ebook)
|
||||||
|
- Formatting consistent across platforms
|
||||||
|
- Code repository public and maintained
|
||||||
|
- Sales page compelling
|
||||||
|
- Pricing competitive
|
||||||
|
- Marketing materials ready
|
||||||
|
|
||||||
|
**Pass Criteria**: Book ready for self-publishing platforms
|
||||||
|
|
||||||
|
**Related Workflows**: Self-Publishing
|
||||||
|
**Related Agents**: book-publisher
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### final-manuscript-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Comprehensive final validation before publication
|
||||||
|
|
||||||
|
**When to Use**: Final quality gate before publisher submission or self-publishing
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- All chapters complete and reviewed
|
||||||
|
- Front matter complete (preface, introduction, TOC)
|
||||||
|
- Back matter complete (appendices, glossary, index)
|
||||||
|
- All code tested and repository public
|
||||||
|
- All images have alt text
|
||||||
|
- Cross-references validated
|
||||||
|
- No placeholder text (TODO, TBD, etc.)
|
||||||
|
- Acknowledgments section complete
|
||||||
|
- Copyright page accurate
|
||||||
|
- Version numbers final
|
||||||
|
|
||||||
|
**Pass Criteria**: Manuscript is publication-ready
|
||||||
|
|
||||||
|
**Related Agents**: book-publisher, technical-editor
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### index-completeness-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Validates book index is comprehensive
|
||||||
|
|
||||||
|
**When to Use**: After creating book index
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- Key concepts indexed
|
||||||
|
- API/function names indexed
|
||||||
|
- Important code examples indexed
|
||||||
|
- Cross-references included
|
||||||
|
- Alphabetically organized
|
||||||
|
- Page numbers accurate
|
||||||
|
- No duplicate entries
|
||||||
|
- See/See also references appropriate
|
||||||
|
|
||||||
|
**Pass Criteria**: Index helps readers find information quickly
|
||||||
|
|
||||||
|
**Related Agents**: book-publisher
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Final QA Checklists
|
||||||
|
|
||||||
|
### diagram-clarity-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Validates diagrams are clear and helpful
|
||||||
|
|
||||||
|
**When to Use**: After creating diagrams
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- Diagram supports text explanation
|
||||||
|
- Labels are legible
|
||||||
|
- Annotations clear
|
||||||
|
- Consistent styling across all diagrams
|
||||||
|
- Alt text descriptive
|
||||||
|
- High resolution (300 DPI for print)
|
||||||
|
- Colors have sufficient contrast
|
||||||
|
- Diagram type appropriate (flowchart, sequence, architecture, etc.)
|
||||||
|
|
||||||
|
**Pass Criteria**: Diagram clarifies concept effectively
|
||||||
|
|
||||||
|
**Related Agents**: screenshot-specialist
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### screenshot-quality-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Validates screenshots meet quality standards
|
||||||
|
|
||||||
|
**When to Use**: After taking screenshots
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- Screenshot shows relevant information clearly
|
||||||
|
- Text is legible
|
||||||
|
- Annotations guide reader's eye
|
||||||
|
- Consistent window/browser styling
|
||||||
|
- No sensitive information visible
|
||||||
|
- High resolution
|
||||||
|
- Cropped appropriately (no unnecessary UI)
|
||||||
|
- Platform noted if platform-specific
|
||||||
|
|
||||||
|
**Pass Criteria**: Screenshots enhance understanding
|
||||||
|
|
||||||
|
**Related Agents**: screenshot-specialist
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### glossary-accuracy-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Validates glossary definitions are accurate and comprehensive
|
||||||
|
|
||||||
|
**When to Use**: After compiling glossary
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- All technical terms defined
|
||||||
|
- Definitions accurate and clear
|
||||||
|
- Alphabetically organized
|
||||||
|
- Cross-references to related terms
|
||||||
|
- Consistent terminology with book
|
||||||
|
- Acronyms expanded
|
||||||
|
- No circular definitions
|
||||||
|
|
||||||
|
**Pass Criteria**: Glossary is helpful reference
|
||||||
|
|
||||||
|
**Related Agents**: api-documenter
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### repository-quality-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Validates code repository meets professional standards
|
||||||
|
|
||||||
|
**When to Use**: Before publishing code repository
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- README.md clear and comprehensive
|
||||||
|
- Installation instructions tested
|
||||||
|
- Folder structure logical
|
||||||
|
- All code tested and working
|
||||||
|
- Tests included
|
||||||
|
- LICENSE file present
|
||||||
|
- CONTRIBUTING.md (if accepting contributions)
|
||||||
|
- .gitignore appropriate
|
||||||
|
- CI/CD pipeline working
|
||||||
|
- Dependency versions pinned
|
||||||
|
|
||||||
|
**Pass Criteria**: Repository is professional and maintainable
|
||||||
|
|
||||||
|
**Related Agents**: sample-code-maintainer
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### cross-platform-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Validates code works across platforms (Windows/macOS/Linux)
|
||||||
|
|
||||||
|
**When to Use**: Cross-platform testing phase
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- Tested on Windows, macOS, Linux
|
||||||
|
- File paths use OS-agnostic methods
|
||||||
|
- Line endings handled correctly
|
||||||
|
- Platform-specific commands documented
|
||||||
|
- Dependencies install on all platforms
|
||||||
|
- No platform-specific bugs
|
||||||
|
|
||||||
|
**Pass Criteria**: Code works on all major platforms
|
||||||
|
|
||||||
|
**Related Agents**: version-manager, code-curator
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### revision-completeness-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Validates all revision tasks complete for book updates
|
||||||
|
|
||||||
|
**When to Use**: Completing 2nd/3rd edition updates
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- All outdated content updated
|
||||||
|
- Version migrations complete
|
||||||
|
- Deprecated code replaced
|
||||||
|
- New features covered
|
||||||
|
- Consistency with existing style maintained
|
||||||
|
- All reviewer feedback incorporated
|
||||||
|
- Revision history documented
|
||||||
|
|
||||||
|
**Pass Criteria**: Revision goals achieved
|
||||||
|
|
||||||
|
**Related Workflows**: Book Edition Update
|
||||||
|
**Related Agents**: book-analyst
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### existing-book-integration-checklist.md
|
||||||
|
|
||||||
|
**Purpose**: Validates new content matches existing book style
|
||||||
|
|
||||||
|
**When to Use**: Adding chapters to existing book
|
||||||
|
|
||||||
|
**Key Criteria**:
|
||||||
|
- Voice and tone consistent
|
||||||
|
- Terminology matches existing chapters
|
||||||
|
- Code style follows existing patterns
|
||||||
|
- Format matches existing chapters
|
||||||
|
- Learning progression maintains flow
|
||||||
|
- Cross-references updated
|
||||||
|
- New chapter integrates smoothly
|
||||||
|
|
||||||
|
**Pass Criteria**: New content feels integrated, not appended
|
||||||
|
|
||||||
|
**Related Workflows**: Add Chapter to Existing Book
|
||||||
|
**Related Agents**: book-analyst, technical-editor
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Checklist Comparison Table
|
||||||
|
|
||||||
|
| Checklist | Phase | Mandatory? | Primary Agent | Focus Area |
|
||||||
|
|-----------|-------|------------|---------------|------------|
|
||||||
|
| learning-objectives-checklist | Planning | Yes | instructional-designer | Pedagogy |
|
||||||
|
| prerequisite-clarity-checklist | Planning | Yes | instructional-designer | Pedagogy |
|
||||||
|
| chapter-completeness-checklist | Drafting | Yes | tutorial-architect | Completeness |
|
||||||
|
| book-proposal-checklist | Drafting | Yes (if pitching) | book-publisher | Proposal |
|
||||||
|
| tutorial-effectiveness-checklist | Drafting | Yes (if tutorials) | tutorial-architect | Usability |
|
||||||
|
| readability-checklist | Drafting | Yes | technical-editor | Clarity |
|
||||||
|
| exercise-difficulty-checklist | Drafting | Yes (if exercises) | exercise-creator | Pedagogy |
|
||||||
|
| code-quality-checklist | Code Quality | Yes | code-curator | Best practices |
|
||||||
|
| code-testing-checklist | Code Quality | Yes | code-curator | Testing |
|
||||||
|
| security-best-practices-checklist | Code Quality | Yes | code-curator | Security |
|
||||||
|
| version-compatibility-checklist | Code Quality | Conditional | version-manager | Compatibility |
|
||||||
|
| performance-considerations-checklist | Code Quality | Recommended | technical-reviewer | Performance |
|
||||||
|
| technical-accuracy-checklist | Review | Yes | technical-reviewer | Accuracy |
|
||||||
|
| accessibility-checklist | Review | Yes | technical-editor | Accessibility |
|
||||||
|
| inclusive-language-checklist | Review | Yes | technical-editor | Inclusivity |
|
||||||
|
| citation-accuracy-checklist | Review | Yes | technical-editor | Attribution |
|
||||||
|
| packtpub-submission-checklist | Publishing | Conditional | book-publisher | Format |
|
||||||
|
| oreilly-format-checklist | Publishing | Conditional | book-publisher | Format |
|
||||||
|
| manning-meap-checklist | Publishing | Conditional | book-publisher | Format |
|
||||||
|
| meap-readiness-checklist | Publishing | Conditional | book-publisher | Early Access |
|
||||||
|
| self-publishing-standards-checklist | Publishing | Conditional | book-publisher | Quality |
|
||||||
|
| final-manuscript-checklist | Publishing | Yes | book-publisher | Completeness |
|
||||||
|
| index-completeness-checklist | Publishing | Conditional | book-publisher | Index |
|
||||||
|
| diagram-clarity-checklist | Final QA | Recommended | screenshot-specialist | Visuals |
|
||||||
|
| screenshot-quality-checklist | Final QA | Recommended | screenshot-specialist | Visuals |
|
||||||
|
| glossary-accuracy-checklist | Final QA | Recommended | api-documenter | Reference |
|
||||||
|
| repository-quality-checklist | Final QA | Yes | sample-code-maintainer | Code |
|
||||||
|
| cross-platform-checklist | Final QA | Conditional | version-manager | Compatibility |
|
||||||
|
| revision-completeness-checklist | Final QA | Conditional | book-analyst | Updates |
|
||||||
|
| existing-book-integration-checklist | Final QA | Conditional | book-analyst | Consistency |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Checklist Roadmap (Quality Gates by Phase)
|
||||||
|
|
||||||
|
### Phase 1: Planning
|
||||||
|
→ learning-objectives-checklist
|
||||||
|
→ prerequisite-clarity-checklist
|
||||||
|
|
||||||
|
### Phase 2: Drafting
|
||||||
|
→ chapter-completeness-checklist
|
||||||
|
→ tutorial-effectiveness-checklist (if tutorials)
|
||||||
|
→ exercise-difficulty-checklist (if exercises)
|
||||||
|
→ readability-checklist
|
||||||
|
|
||||||
|
### Phase 3: Code Development
|
||||||
|
→ code-quality-checklist
|
||||||
|
→ code-testing-checklist
|
||||||
|
→ security-best-practices-checklist
|
||||||
|
→ version-compatibility-checklist (if multi-version)
|
||||||
|
|
||||||
|
### Phase 4: Review
|
||||||
|
→ technical-accuracy-checklist (CRITICAL GATE)
|
||||||
|
→ performance-considerations-checklist
|
||||||
|
→ accessibility-checklist
|
||||||
|
→ inclusive-language-checklist
|
||||||
|
→ citation-accuracy-checklist
|
||||||
|
|
||||||
|
### Phase 5: Pre-Publication
|
||||||
|
→ diagram-clarity-checklist (if diagrams)
|
||||||
|
→ screenshot-quality-checklist (if screenshots)
|
||||||
|
→ glossary-accuracy-checklist (if glossary)
|
||||||
|
→ repository-quality-checklist
|
||||||
|
→ cross-platform-checklist (if multi-platform)
|
||||||
|
|
||||||
|
### Phase 6: Publication Prep
|
||||||
|
→ Publisher-specific checklist (PacktPub, O'Reilly, or Manning)
|
||||||
|
→ final-manuscript-checklist (FINAL GATE)
|
||||||
|
→ index-completeness-checklist (if print book)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quality Gate Recommendations
|
||||||
|
|
||||||
|
### Mandatory (Must Pass)
|
||||||
|
- learning-objectives-checklist
|
||||||
|
- prerequisite-clarity-checklist
|
||||||
|
- chapter-completeness-checklist
|
||||||
|
- code-quality-checklist
|
||||||
|
- code-testing-checklist
|
||||||
|
- security-best-practices-checklist
|
||||||
|
- technical-accuracy-checklist
|
||||||
|
- accessibility-checklist
|
||||||
|
- final-manuscript-checklist
|
||||||
|
|
||||||
|
### Highly Recommended
|
||||||
|
- readability-checklist
|
||||||
|
- inclusive-language-checklist
|
||||||
|
- repository-quality-checklist
|
||||||
|
- Publisher-specific checklist
|
||||||
|
|
||||||
|
### Conditional (Use When Applicable)
|
||||||
|
- book-proposal-checklist (if pitching)
|
||||||
|
- tutorial-effectiveness-checklist (if tutorials)
|
||||||
|
- exercise-difficulty-checklist (if exercises)
|
||||||
|
- version-compatibility-checklist (if multi-version)
|
||||||
|
- performance-considerations-checklist (if performance-critical)
|
||||||
|
- diagram/screenshot checklists (if visuals)
|
||||||
|
- glossary-accuracy-checklist (if glossary)
|
||||||
|
- index-completeness-checklist (if print)
|
||||||
|
- cross-platform-checklist (if multi-platform)
|
||||||
|
- revision/integration checklists (if brownfield)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Conclusion
|
||||||
|
|
||||||
|
The BMad Technical Writing Expansion Pack's **31 quality checklists** provide comprehensive validation at every stage of book authoring. By using checklists as quality gates, you can:
|
||||||
|
|
||||||
|
- **Prevent defects early** through systematic validation
|
||||||
|
- **Maintain consistency** across chapters and versions
|
||||||
|
- **Meet professional standards** for publication
|
||||||
|
- **Ensure accessibility** and inclusivity
|
||||||
|
- **Validate technical accuracy** before release
|
||||||
|
- **Track quality** throughout the process
|
||||||
|
|
||||||
|
**Critical Checklists**:
|
||||||
|
- technical-accuracy-checklist - Non-negotiable quality gate
|
||||||
|
- code-testing-checklist - Ensures code reliability
|
||||||
|
- final-manuscript-checklist - Publication readiness
|
||||||
|
- accessibility-checklist - Universal access
|
||||||
|
|
||||||
|
**Total checklist count**: 31
|
||||||
|
**Word count**: ~2,300 words
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Related Documentation**:
|
||||||
|
- [Agent Reference Guide](agent-reference.md) - Agents that execute checklists
|
||||||
|
- [Workflow Guide](workflow-guide.md) - Workflows that use checklists
|
||||||
|
- [Task Reference](task-reference.md) - Tasks that run checklists
|
||||||
|
- [User Guide](user-guide.md) - Quality gates in context
|
||||||
|
|
@ -0,0 +1,663 @@
|
||||||
|
# Task Reference
|
||||||
|
|
||||||
|
## Introduction
|
||||||
|
|
||||||
|
The BMad Technical Writing Expansion Pack provides **33 executable tasks** that guide agents through specific workflows. Tasks are procedural markdown files with step-by-step instructions that agents follow exactly.
|
||||||
|
|
||||||
|
This comprehensive reference documents all 33 tasks organized by phase, with:
|
||||||
|
|
||||||
|
- **Task name and purpose** - What the task accomplishes
|
||||||
|
- **When to use** - Specific scenarios
|
||||||
|
- **Prerequisites** - What's needed to start
|
||||||
|
- **Outputs** - Deliverables produced
|
||||||
|
- **Related workflows** - Which workflows use this task
|
||||||
|
- **Related agents** - Which agents execute this task
|
||||||
|
- **Estimated time** - Typical duration
|
||||||
|
|
||||||
|
### Task Categories
|
||||||
|
|
||||||
|
- **Planning Phase (6 tasks)**: Book outlines, learning paths, proposals
|
||||||
|
- **Chapter Development (8 tasks)**: Drafts, outlines, summaries, introductions
|
||||||
|
- **Code Management (5 tasks)**: Examples, testing, repositories, version checks
|
||||||
|
- **Review & Editing (4 tasks)**: Technical reviews, copy editing, feedback incorporation
|
||||||
|
- **Publishing (7 tasks)**: Packaging, MEAP, self-publishing, indexes
|
||||||
|
- **Documentation (3 tasks)**: Glossaries, API docs, diagrams
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Planning Phase Tasks
|
||||||
|
|
||||||
|
### design-book-outline.md
|
||||||
|
|
||||||
|
**Purpose**: Creates detailed pedagogical book outline with learning progression
|
||||||
|
|
||||||
|
**When to Use**: Planning new technical book, need structured chapter-by-chapter outline
|
||||||
|
|
||||||
|
**Prerequisites**:
|
||||||
|
- Book topic and target audience defined
|
||||||
|
- Publisher target identified (optional)
|
||||||
|
|
||||||
|
**Outputs**: `book-outline.md` with chapters, learning objectives, prerequisites
|
||||||
|
|
||||||
|
**Related Workflows**: Book Planning Workflow
|
||||||
|
**Related Agents**: instructional-designer
|
||||||
|
**Estimated Time**: 8-12 hours
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### create-learning-objectives.md
|
||||||
|
|
||||||
|
**Purpose**: Defines measurable learning outcomes using Bloom's taxonomy
|
||||||
|
|
||||||
|
**When to Use**: Planning chapter content, need specific learning goals
|
||||||
|
|
||||||
|
**Prerequisites**: Chapter topic defined
|
||||||
|
|
||||||
|
**Outputs**: Learning objectives (3-5 per chapter)
|
||||||
|
|
||||||
|
**Related Agents**: instructional-designer
|
||||||
|
**Estimated Time**: 1-2 hours
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### design-learning-path.md
|
||||||
|
|
||||||
|
**Purpose**: Maps prerequisite dependencies and skill progression across chapters
|
||||||
|
|
||||||
|
**When to Use**: Validating book learning flow, ensuring no knowledge gaps
|
||||||
|
|
||||||
|
**Prerequisites**: Book outline complete
|
||||||
|
|
||||||
|
**Outputs**: Learning path diagram with dependencies
|
||||||
|
|
||||||
|
**Related Agents**: learning-path-designer, instructional-designer
|
||||||
|
**Estimated Time**: 3-5 hours
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### plan-book-revision.md
|
||||||
|
|
||||||
|
**Purpose**: Creates strategic plan for updating existing book (2nd/3rd edition)
|
||||||
|
|
||||||
|
**When to Use**: Planning book updates, version migration, content refresh
|
||||||
|
|
||||||
|
**Prerequisites**: Existing book analysis complete
|
||||||
|
|
||||||
|
**Outputs**: `revision-plan.md` with surgical update strategy
|
||||||
|
|
||||||
|
**Related Workflows**: Book Edition Update Workflow
|
||||||
|
**Related Agents**: book-analyst
|
||||||
|
**Estimated Time**: 6-12 hours
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### analyze-existing-book.md
|
||||||
|
|
||||||
|
**Purpose**: Analyzes existing book structure, style, patterns for consistency
|
||||||
|
|
||||||
|
**When to Use**: Planning revisions, adding chapters to existing book
|
||||||
|
|
||||||
|
**Prerequisites**: Access to existing book content
|
||||||
|
|
||||||
|
**Outputs**: `book-analysis-report.md` with patterns extracted
|
||||||
|
|
||||||
|
**Related Workflows**: Book Edition Update Workflow, Add Chapter Workflow
|
||||||
|
**Related Agents**: book-analyst
|
||||||
|
**Estimated Time**: 8-16 hours
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### extract-code-patterns.md
|
||||||
|
|
||||||
|
**Purpose**: Extracts code style and conventions from existing book
|
||||||
|
|
||||||
|
**When to Use**: Maintaining consistency when updating existing code examples
|
||||||
|
|
||||||
|
**Prerequisites**: Existing book with code examples
|
||||||
|
|
||||||
|
**Outputs**: Code style guide extracted from existing patterns
|
||||||
|
|
||||||
|
**Related Agents**: book-analyst
|
||||||
|
**Estimated Time**: 2-4 hours
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Chapter Development Tasks
|
||||||
|
|
||||||
|
### create-chapter-outline.md
|
||||||
|
|
||||||
|
**Purpose**: Creates detailed chapter structure with sections, exercises, code examples
|
||||||
|
|
||||||
|
**When to Use**: Before writing chapter content
|
||||||
|
|
||||||
|
**Prerequisites**: Book outline with chapter objectives
|
||||||
|
|
||||||
|
**Outputs**: `chapter-{n}-outline.md`
|
||||||
|
|
||||||
|
**Related Workflows**: Chapter Development Workflow
|
||||||
|
**Related Agents**: tutorial-architect
|
||||||
|
**Estimated Time**: 2-4 hours
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### write-chapter-draft.md
|
||||||
|
|
||||||
|
**Purpose**: Writes complete chapter draft from outline
|
||||||
|
|
||||||
|
**When to Use**: Traditional full-chapter writing approach
|
||||||
|
|
||||||
|
**Prerequisites**: Chapter outline, code examples developed
|
||||||
|
|
||||||
|
**Outputs**: `chapter-{n}-draft.md`
|
||||||
|
|
||||||
|
**Related Agents**: tutorial-architect
|
||||||
|
**Estimated Time**: 12-20 hours (15-30 page chapter)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### write-introduction.md
|
||||||
|
|
||||||
|
**Purpose**: Writes chapter introduction with hook, overview, learning goals
|
||||||
|
|
||||||
|
**When to Use**: Starting chapter or section writing
|
||||||
|
|
||||||
|
**Prerequisites**: Chapter outline
|
||||||
|
|
||||||
|
**Outputs**: Introduction section (1-2 pages)
|
||||||
|
|
||||||
|
**Related Agents**: tutorial-architect
|
||||||
|
**Estimated Time**: 1-2 hours
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### write-summary.md
|
||||||
|
|
||||||
|
**Purpose**: Creates chapter conclusion with key takeaways and next steps
|
||||||
|
|
||||||
|
**When to Use**: Completing chapter writing
|
||||||
|
|
||||||
|
**Prerequisites**: Chapter content complete
|
||||||
|
|
||||||
|
**Outputs**: Summary section (1 page)
|
||||||
|
|
||||||
|
**Related Agents**: tutorial-architect
|
||||||
|
**Estimated Time**: 1 hour
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### create-preface.md
|
||||||
|
|
||||||
|
**Purpose**: Writes book preface (author voice, how to use book)
|
||||||
|
|
||||||
|
**When to Use**: Completing book front matter
|
||||||
|
|
||||||
|
**Prerequisites**: Book content substantially complete
|
||||||
|
|
||||||
|
**Outputs**: `preface.md`
|
||||||
|
|
||||||
|
**Related Agents**: book-publisher
|
||||||
|
**Estimated Time**: 2-3 hours
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### create-appendix.md
|
||||||
|
|
||||||
|
**Purpose**: Creates reference appendix
|
||||||
|
|
||||||
|
**When to Use**: Adding supplementary reference material
|
||||||
|
|
||||||
|
**Prerequisites**: Main content complete
|
||||||
|
|
||||||
|
**Outputs**: Appendix markdown file
|
||||||
|
|
||||||
|
**Related Agents**: api-documenter
|
||||||
|
**Estimated Time**: 2-4 hours per appendix
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### develop-tutorial.md
|
||||||
|
|
||||||
|
**Purpose**: Creates step-by-step hands-on tutorial
|
||||||
|
|
||||||
|
**When to Use**: Building tutorial sections, workshop materials
|
||||||
|
|
||||||
|
**Prerequisites**: Tutorial plan, learning objective defined
|
||||||
|
|
||||||
|
**Outputs**: Complete tutorial with steps, code, troubleshooting
|
||||||
|
|
||||||
|
**Related Workflows**: Tutorial Creation Workflow
|
||||||
|
**Related Agents**: tutorial-architect
|
||||||
|
**Estimated Time**: 4-8 hours
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### design-exercises.md
|
||||||
|
|
||||||
|
**Purpose**: Creates practice problem sets aligned with learning objectives
|
||||||
|
|
||||||
|
**When to Use**: Adding exercises to chapters
|
||||||
|
|
||||||
|
**Prerequisites**: Learning objectives defined
|
||||||
|
|
||||||
|
**Outputs**: Exercise set with solutions
|
||||||
|
|
||||||
|
**Related Agents**: exercise-creator
|
||||||
|
**Estimated Time**: 2-4 hours
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Code Management Tasks
|
||||||
|
|
||||||
|
### create-code-example.md
|
||||||
|
|
||||||
|
**Purpose**: Develops single tested code example with documentation
|
||||||
|
|
||||||
|
**When to Use**: Creating code snippets for chapters
|
||||||
|
|
||||||
|
**Prerequisites**: Example purpose and target version defined
|
||||||
|
|
||||||
|
**Outputs**: Tested code file with tests and README
|
||||||
|
|
||||||
|
**Related Workflows**: Code Example Workflow
|
||||||
|
**Related Agents**: code-curator
|
||||||
|
**Estimated Time**: 1-4 hours
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### test-code-examples.md
|
||||||
|
|
||||||
|
**Purpose**: Tests all code examples across versions and platforms
|
||||||
|
|
||||||
|
**When to Use**: Validating code quality before chapter finalization
|
||||||
|
|
||||||
|
**Prerequisites**: Code examples developed
|
||||||
|
|
||||||
|
**Outputs**: Test results report
|
||||||
|
|
||||||
|
**Related Agents**: code-curator, sample-code-maintainer
|
||||||
|
**Estimated Time**: 1-2 hours per chapter
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### setup-code-repository.md
|
||||||
|
|
||||||
|
**Purpose**: Organizes code repository structure with testing and CI/CD
|
||||||
|
|
||||||
|
**When to Use**: Starting book project, need organized code structure
|
||||||
|
|
||||||
|
**Prerequisites**: Book outline defining chapter count
|
||||||
|
|
||||||
|
**Outputs**: Repository with folders, README, CI/CD pipeline
|
||||||
|
|
||||||
|
**Related Agents**: sample-code-maintainer
|
||||||
|
**Estimated Time**: 2-4 hours
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### version-matrix-check.md
|
||||||
|
|
||||||
|
**Purpose**: Defines and tests version compatibility matrix
|
||||||
|
|
||||||
|
**When to Use**: Multi-version book (e.g., Python 3.10, 3.11, 3.12)
|
||||||
|
|
||||||
|
**Prerequisites**: Target versions identified
|
||||||
|
|
||||||
|
**Outputs**: Version matrix with test results
|
||||||
|
|
||||||
|
**Related Agents**: version-manager
|
||||||
|
**Estimated Time**: 2-3 hours setup, ongoing testing
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### update-chapter-for-version.md
|
||||||
|
|
||||||
|
**Purpose**: Updates chapter code for new technology version
|
||||||
|
|
||||||
|
**When to Use**: Version migration for 2nd edition
|
||||||
|
|
||||||
|
**Prerequisites**: Version impact analysis complete
|
||||||
|
|
||||||
|
**Outputs**: Updated chapter with migrated code
|
||||||
|
|
||||||
|
**Related Workflows**: Book Edition Update Workflow
|
||||||
|
**Related Agents**: version-manager, code-curator
|
||||||
|
**Estimated Time**: 2-6 hours per chapter (varies)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Review & Editing Tasks
|
||||||
|
|
||||||
|
### technical-review-chapter.md
|
||||||
|
|
||||||
|
**Purpose**: Performs comprehensive technical review of chapter
|
||||||
|
|
||||||
|
**When to Use**: Validating technical accuracy before publication
|
||||||
|
|
||||||
|
**Prerequisites**: Chapter draft complete
|
||||||
|
|
||||||
|
**Outputs**: `technical-review-report.md` with findings
|
||||||
|
|
||||||
|
**Related Workflows**: Technical Review Workflow, Chapter Assembly Workflow
|
||||||
|
**Related Agents**: technical-reviewer
|
||||||
|
**Estimated Time**: 3-5 hours per chapter
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### copy-edit-chapter.md
|
||||||
|
|
||||||
|
**Purpose**: Professional copy editing for clarity, consistency, style
|
||||||
|
|
||||||
|
**When to Use**: After technical review, before finalization
|
||||||
|
|
||||||
|
**Prerequisites**: Technically accurate chapter
|
||||||
|
|
||||||
|
**Outputs**: Edited chapter with change summary
|
||||||
|
|
||||||
|
**Related Agents**: technical-editor
|
||||||
|
**Estimated Time**: 2-4 hours per chapter
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### incorporate-reviewer-feedback.md
|
||||||
|
|
||||||
|
**Purpose**: Systematically addresses review comments and feedback
|
||||||
|
|
||||||
|
**When to Use**: After receiving technical review, beta reader, or publisher feedback
|
||||||
|
|
||||||
|
**Prerequisites**: Review report with categorized feedback
|
||||||
|
|
||||||
|
**Outputs**: Revised chapter addressing all feedback
|
||||||
|
|
||||||
|
**Related Workflows**: Incorporate Review Feedback Workflow
|
||||||
|
**Related Agents**: tutorial-architect, technical-reviewer
|
||||||
|
**Estimated Time**: 4-12 hours (varies by feedback volume)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### validate-cross-references.md
|
||||||
|
|
||||||
|
**Purpose**: Verifies all internal links, chapter references, and figure citations
|
||||||
|
|
||||||
|
**When to Use**: Final validation before publication
|
||||||
|
|
||||||
|
**Prerequisites**: Book content complete
|
||||||
|
|
||||||
|
**Outputs**: Validation report with broken references
|
||||||
|
|
||||||
|
**Related Agents**: technical-editor
|
||||||
|
**Estimated Time**: 1-2 hours
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Publishing Tasks
|
||||||
|
|
||||||
|
### package-for-publisher.md
|
||||||
|
|
||||||
|
**Purpose**: Prepares manuscript package for publisher submission
|
||||||
|
|
||||||
|
**When to Use**: Submitting to traditional publisher
|
||||||
|
|
||||||
|
**Prerequisites**: Book complete, publisher identified
|
||||||
|
|
||||||
|
**Outputs**: Formatted manuscript bundle
|
||||||
|
|
||||||
|
**Related Workflows**: PacktPub/O'Reilly/Manning Submission Workflows
|
||||||
|
**Related Agents**: book-publisher
|
||||||
|
**Estimated Time**: 3-6 hours
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### prepare-meap-chapter.md
|
||||||
|
|
||||||
|
**Purpose**: Formats chapter for Manning Early Access Program
|
||||||
|
|
||||||
|
**When to Use**: Incremental Manning MEAP releases
|
||||||
|
|
||||||
|
**Prerequisites**: Chapter complete and reviewed
|
||||||
|
|
||||||
|
**Outputs**: MEAP-ready chapter
|
||||||
|
|
||||||
|
**Related Workflows**: Manning MEAP Workflow
|
||||||
|
**Related Agents**: book-publisher
|
||||||
|
**Estimated Time**: 1-2 hours per chapter
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### self-publish-prep.md
|
||||||
|
|
||||||
|
**Purpose**: Prepares book for self-publishing platforms
|
||||||
|
|
||||||
|
**When to Use**: Self-publishing (Leanpub, Gumroad, Amazon KDP)
|
||||||
|
|
||||||
|
**Prerequisites**: Book complete
|
||||||
|
|
||||||
|
**Outputs**: Platform-specific formatted files
|
||||||
|
|
||||||
|
**Related Workflows**: Self-Publishing Workflow
|
||||||
|
**Related Agents**: book-publisher
|
||||||
|
**Estimated Time**: 4-8 hours
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### create-index-entries.md
|
||||||
|
|
||||||
|
**Purpose**: Generates book index from marked terms
|
||||||
|
|
||||||
|
**When to Use**: Finalizing book for print publication
|
||||||
|
|
||||||
|
**Prerequisites**: Index terms marked throughout manuscript
|
||||||
|
|
||||||
|
**Outputs**: Book index
|
||||||
|
|
||||||
|
**Related Agents**: book-publisher
|
||||||
|
**Estimated Time**: 3-5 hours
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### create-solutions.md
|
||||||
|
|
||||||
|
**Purpose**: Creates detailed solutions for exercises
|
||||||
|
|
||||||
|
**When to Use**: Adding solutions appendix or separate guide
|
||||||
|
|
||||||
|
**Prerequisites**: Exercise sets defined
|
||||||
|
|
||||||
|
**Outputs**: Solutions with explanations
|
||||||
|
|
||||||
|
**Related Agents**: exercise-creator
|
||||||
|
**Estimated Time**: 2-3 hours
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### take-screenshots.md
|
||||||
|
|
||||||
|
**Purpose**: Plans and captures screenshots for book
|
||||||
|
|
||||||
|
**When to Use**: Need visual documentation
|
||||||
|
|
||||||
|
**Prerequisites**: Application/tool ready for screenshots
|
||||||
|
|
||||||
|
**Outputs**: Screenshot files with annotations
|
||||||
|
|
||||||
|
**Related Agents**: screenshot-specialist
|
||||||
|
**Estimated Time**: 1-2 hours per chapter
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### design-diagram-set.md
|
||||||
|
|
||||||
|
**Purpose**: Plans complete set of diagrams for chapter or book
|
||||||
|
|
||||||
|
**When to Use**: Identifying all visual needs upfront
|
||||||
|
|
||||||
|
**Prerequisites**: Content outline
|
||||||
|
|
||||||
|
**Outputs**: Diagram specifications list
|
||||||
|
|
||||||
|
**Related Agents**: screenshot-specialist
|
||||||
|
**Estimated Time**: 2-3 hours
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Documentation Tasks
|
||||||
|
|
||||||
|
### generate-api-docs.md
|
||||||
|
|
||||||
|
**Purpose**: Creates comprehensive API reference documentation
|
||||||
|
|
||||||
|
**When to Use**: Documenting APIs, libraries, frameworks
|
||||||
|
|
||||||
|
**Prerequisites**: API code available
|
||||||
|
|
||||||
|
**Outputs**: API reference with parameters, returns, examples
|
||||||
|
|
||||||
|
**Related Agents**: api-documenter
|
||||||
|
**Estimated Time**: 4-8 hours (varies by API size)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### build-glossary.md
|
||||||
|
|
||||||
|
**Purpose**: Compiles terminology glossary from book content
|
||||||
|
|
||||||
|
**When to Use**: Creating book glossary
|
||||||
|
|
||||||
|
**Prerequisites**: Book content with terms identified
|
||||||
|
|
||||||
|
**Outputs**: `glossary.md` with alphabetized definitions
|
||||||
|
|
||||||
|
**Related Agents**: api-documenter
|
||||||
|
**Estimated Time**: 2-4 hours
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### create-diagram-spec.md
|
||||||
|
|
||||||
|
**Purpose**: Creates specification for single technical diagram
|
||||||
|
|
||||||
|
**When to Use**: Need diagram for concept explanation
|
||||||
|
|
||||||
|
**Prerequisites**: Concept to visualize defined
|
||||||
|
|
||||||
|
**Outputs**: Diagram specification (Mermaid code or detailed description)
|
||||||
|
|
||||||
|
**Related Agents**: screenshot-specialist
|
||||||
|
**Estimated Time**: 30 min - 1 hour per diagram
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Task Comparison Table
|
||||||
|
|
||||||
|
| Task | Phase | Est. Time | Primary Agent | Complexity |
|
||||||
|
|------|-------|-----------|---------------|------------|
|
||||||
|
| design-book-outline | Planning | 8-12 hrs | instructional-designer | Medium |
|
||||||
|
| create-learning-objectives | Planning | 1-2 hrs | instructional-designer | Low |
|
||||||
|
| design-learning-path | Planning | 3-5 hrs | learning-path-designer | Medium |
|
||||||
|
| plan-book-revision | Planning | 6-12 hrs | book-analyst | Medium |
|
||||||
|
| analyze-existing-book | Planning | 8-16 hrs | book-analyst | High |
|
||||||
|
| extract-code-patterns | Planning | 2-4 hrs | book-analyst | Medium |
|
||||||
|
| create-chapter-outline | Chapter Dev | 2-4 hrs | tutorial-architect | Low |
|
||||||
|
| write-chapter-draft | Chapter Dev | 12-20 hrs | tutorial-architect | High |
|
||||||
|
| write-introduction | Chapter Dev | 1-2 hrs | tutorial-architect | Low |
|
||||||
|
| write-summary | Chapter Dev | 1 hr | tutorial-architect | Low |
|
||||||
|
| create-preface | Chapter Dev | 2-3 hrs | book-publisher | Low |
|
||||||
|
| create-appendix | Chapter Dev | 2-4 hrs | api-documenter | Medium |
|
||||||
|
| develop-tutorial | Chapter Dev | 4-8 hrs | tutorial-architect | Medium |
|
||||||
|
| design-exercises | Chapter Dev | 2-4 hrs | exercise-creator | Medium |
|
||||||
|
| create-code-example | Code Mgmt | 1-4 hrs | code-curator | Low-Med |
|
||||||
|
| test-code-examples | Code Mgmt | 1-2 hrs | code-curator | Low |
|
||||||
|
| setup-code-repository | Code Mgmt | 2-4 hrs | sample-code-maintainer | Medium |
|
||||||
|
| version-matrix-check | Code Mgmt | 2-3 hrs | version-manager | Medium |
|
||||||
|
| update-chapter-for-version | Code Mgmt | 2-6 hrs | version-manager | Medium |
|
||||||
|
| technical-review-chapter | Review | 3-5 hrs | technical-reviewer | Medium |
|
||||||
|
| copy-edit-chapter | Review | 2-4 hrs | technical-editor | Medium |
|
||||||
|
| incorporate-reviewer-feedback | Review | 4-12 hrs | tutorial-architect | Varies |
|
||||||
|
| validate-cross-references | Review | 1-2 hrs | technical-editor | Low |
|
||||||
|
| package-for-publisher | Publishing | 3-6 hrs | book-publisher | Medium |
|
||||||
|
| prepare-meap-chapter | Publishing | 1-2 hrs | book-publisher | Low |
|
||||||
|
| self-publish-prep | Publishing | 4-8 hrs | book-publisher | Medium |
|
||||||
|
| create-index-entries | Publishing | 3-5 hrs | book-publisher | Medium |
|
||||||
|
| create-solutions | Publishing | 2-3 hrs | exercise-creator | Low |
|
||||||
|
| take-screenshots | Publishing | 1-2 hrs | screenshot-specialist | Low |
|
||||||
|
| design-diagram-set | Publishing | 2-3 hrs | screenshot-specialist | Medium |
|
||||||
|
| generate-api-docs | Documentation | 4-8 hrs | api-documenter | Medium |
|
||||||
|
| build-glossary | Documentation | 2-4 hrs | api-documenter | Low |
|
||||||
|
| create-diagram-spec | Documentation | 30m-1hr | screenshot-specialist | Low |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quick Reference: Most Common Tasks
|
||||||
|
|
||||||
|
### For New Books
|
||||||
|
1. `design-book-outline.md` - Create book structure
|
||||||
|
2. `create-chapter-outline.md` - Plan each chapter
|
||||||
|
3. `create-code-example.md` - Develop code examples
|
||||||
|
4. `write-chapter-draft.md` or section-driven workflow
|
||||||
|
5. `technical-review-chapter.md` - Validate accuracy
|
||||||
|
6. `copy-edit-chapter.md` - Polish quality
|
||||||
|
7. `package-for-publisher.md` - Submit to publisher
|
||||||
|
|
||||||
|
### For Existing Book Updates
|
||||||
|
1. `analyze-existing-book.md` - Understand current state
|
||||||
|
2. `plan-book-revision.md` - Strategic update plan
|
||||||
|
3. `update-chapter-for-version.md` - Migrate code
|
||||||
|
4. `incorporate-reviewer-feedback.md` - Address feedback
|
||||||
|
5. `package-for-publisher.md` - Resubmit
|
||||||
|
|
||||||
|
### For Tutorial-Focused Content
|
||||||
|
1. `create-learning-objectives.md` - Define outcomes
|
||||||
|
2. `develop-tutorial.md` - Build step-by-step tutorial
|
||||||
|
3. `create-code-example.md` - Create tested code
|
||||||
|
4. `design-exercises.md` - Add practice problems
|
||||||
|
5. `create-solutions.md` - Provide solutions
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Task Selection by Phase
|
||||||
|
|
||||||
|
**Planning Phase**: Start here for new books
|
||||||
|
- design-book-outline, create-learning-objectives, design-learning-path
|
||||||
|
|
||||||
|
**Chapter Development**: Main content creation
|
||||||
|
- create-chapter-outline, write-chapter-draft, write-introduction, write-summary, develop-tutorial, design-exercises
|
||||||
|
|
||||||
|
**Code Management**: Ensure code quality
|
||||||
|
- create-code-example, test-code-examples, setup-code-repository
|
||||||
|
|
||||||
|
**Review & Editing**: Quality assurance
|
||||||
|
- technical-review-chapter, copy-edit-chapter, incorporate-reviewer-feedback
|
||||||
|
|
||||||
|
**Publishing**: Prepare for release
|
||||||
|
- package-for-publisher, prepare-meap-chapter, self-publish-prep, create-index-entries
|
||||||
|
|
||||||
|
**Documentation**: Reference materials
|
||||||
|
- generate-api-docs, build-glossary, create-diagram-spec
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Conclusion
|
||||||
|
|
||||||
|
The BMad Technical Writing Expansion Pack's **33 executable tasks** provide step-by-step procedural guidance for every aspect of technical book authoring. By understanding each task's purpose, prerequisites, and outputs, you can:
|
||||||
|
|
||||||
|
- **Execute workflows** efficiently with clear procedures
|
||||||
|
- **Track progress** using task completion
|
||||||
|
- **Estimate time** accurately for planning
|
||||||
|
- **Coordinate agents** with specific task assignments
|
||||||
|
- **Maintain quality** through structured procedures
|
||||||
|
|
||||||
|
**Most Critical Tasks**:
|
||||||
|
- `design-book-outline.md` - Foundation of book planning
|
||||||
|
- `create-chapter-outline.md` - Essential for chapter development
|
||||||
|
- `technical-review-chapter.md` - Ensures technical accuracy
|
||||||
|
- `copy-edit-chapter.md` - Professional polish
|
||||||
|
|
||||||
|
**Total task count**: 33
|
||||||
|
**Word count**: ~2,500 words
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Related Documentation**:
|
||||||
|
- [Agent Reference Guide](agent-reference.md) - Agents that execute these tasks
|
||||||
|
- [Workflow Guide](workflow-guide.md) - Workflows that orchestrate tasks
|
||||||
|
- [Template Gallery](template-gallery.md) - Templates used by tasks
|
||||||
|
- [User Guide](user-guide.md) - How tasks fit into the process
|
||||||
|
|
@ -0,0 +1,738 @@
|
||||||
|
# Template Gallery
|
||||||
|
|
||||||
|
## Introduction
|
||||||
|
|
||||||
|
The BMad Technical Writing Expansion Pack provides **18 YAML templates** that structure documentation creation across the entire book authoring lifecycle. Each template defines sections with embedded LLM instructions, ensuring consistent, high-quality output.
|
||||||
|
|
||||||
|
This comprehensive gallery showcases all 18 templates organized by category, with:
|
||||||
|
|
||||||
|
- **Template name and description** - What the template creates
|
||||||
|
- **Purpose** - When and why to use it
|
||||||
|
- **Related workflows** - Which workflows use this template
|
||||||
|
- **Related agents** - Which agents execute this template
|
||||||
|
- **Sample output** - Filled template examples showing structure
|
||||||
|
- **Customization notes** - How to adapt the template
|
||||||
|
|
||||||
|
### Template Categories
|
||||||
|
|
||||||
|
- **Planning Templates (3)**: Book proposals, outlines, chapter planning
|
||||||
|
- **Chapter Content Templates (5)**: Section plans, drafts, introductions, prefaces, appendices
|
||||||
|
- **Code Templates (2)**: Code examples, API reference
|
||||||
|
- **Learning Templates (2)**: Learning objectives, exercise sets
|
||||||
|
- **Tutorial Templates (1)**: Tutorial sections
|
||||||
|
- **Review Templates (2)**: Technical reviews, revision plans
|
||||||
|
- **Visual Templates (1)**: Diagram specifications
|
||||||
|
- **Documentation Templates (2)**: Glossaries, book analysis reports
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Planning Templates
|
||||||
|
|
||||||
|
### Book Outline Template
|
||||||
|
|
||||||
|
**ID**: `book-outline-tmpl.yaml`
|
||||||
|
**Output**: `{book_title}-outline.md`
|
||||||
|
**Elicitation**: Required
|
||||||
|
|
||||||
|
#### Purpose
|
||||||
|
|
||||||
|
Creates complete book structure with learning path and chapter-by-chapter breakdown. Used at the start of book planning to define pedagogical progression and content scope.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Planning new technical book from scratch
|
||||||
|
- Pitching book proposal to publisher (use with book-proposal-tmpl)
|
||||||
|
- Need structured learning progression across chapters
|
||||||
|
- Validating book concept before writing
|
||||||
|
|
||||||
|
#### Sections Defined
|
||||||
|
|
||||||
|
1. **Book Metadata** - Title, audience, prerequisites, outcomes, length, publisher, tech stack
|
||||||
|
2. **Front Matter Plan** - Preface, about author, conventions, setup instructions
|
||||||
|
3. **Part/Section Organization** - Grouping chapters into parts with learning arcs
|
||||||
|
4. **Chapter-by-Chapter Outline** - Objectives, topics, exercises, code examples, page counts
|
||||||
|
5. **Learning Path Progression** - Difficulty increase, scaffolding, Bloom's taxonomy mapping
|
||||||
|
6. **Back Matter Plan** - Appendices, glossary, index, resources
|
||||||
|
7. **Code Repository Plan** - Folder structure, testing strategy, version support
|
||||||
|
|
||||||
|
#### Related Workflows
|
||||||
|
|
||||||
|
- Book Planning Workflow (primary)
|
||||||
|
- Chapter Development Workflow (uses this as input)
|
||||||
|
|
||||||
|
#### Related Agents
|
||||||
|
|
||||||
|
- **instructional-designer** (creates this)
|
||||||
|
- **tutorial-architect** (uses for chapter planning)
|
||||||
|
|
||||||
|
#### Sample Output
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Python Data Structures Handbook - Book Outline
|
||||||
|
|
||||||
|
## Book Metadata
|
||||||
|
|
||||||
|
**Title**: Python Data Structures Handbook: Mastering Lists, Dictionaries, Sets, and Beyond
|
||||||
|
**Subtitle**: A Practical Guide to Python's Built-in Data Structures
|
||||||
|
**Target Audience**: Intermediate Python developers (1-2 years experience)
|
||||||
|
**Prerequisites**:
|
||||||
|
- Python 3.10+ installed
|
||||||
|
- Basic Python syntax (variables, functions, control flow)
|
||||||
|
- Object-oriented programming fundamentals
|
||||||
|
|
||||||
|
**Learning Outcomes**:
|
||||||
|
By the end of this book, readers will:
|
||||||
|
- Master Python's built-in data structures (lists, tuples, dictionaries, sets)
|
||||||
|
- Implement custom data structures (stacks, queues, trees, graphs)
|
||||||
|
- Analyze time and space complexity of data structure operations
|
||||||
|
- Choose optimal data structures for specific use cases
|
||||||
|
- Optimize performance using appropriate structures
|
||||||
|
|
||||||
|
**Estimated Length**: 350-400 pages
|
||||||
|
**Publisher Target**: O'Reilly Media
|
||||||
|
**Technology Stack**: Python 3.11+, pytest for testing
|
||||||
|
|
||||||
|
## Part Structure
|
||||||
|
|
||||||
|
**Part I: Built-in Data Structures** (Chapters 1-5)
|
||||||
|
Foundation in Python's core data structures. Readers master lists, tuples, dictionaries, and sets before moving to advanced topics.
|
||||||
|
|
||||||
|
**Part II: Custom Data Structures** (Chapters 6-9)
|
||||||
|
Implementation of classic computer science data structures. Builds on Part I concepts to create stacks, queues, trees, and graphs.
|
||||||
|
|
||||||
|
**Part III: Real-World Applications** (Chapters 10-12)
|
||||||
|
Practical applications and performance optimization. Readers apply knowledge to solve real problems efficiently.
|
||||||
|
|
||||||
|
## Chapter-by-Chapter Outline
|
||||||
|
|
||||||
|
### Chapter 1: List Fundamentals
|
||||||
|
|
||||||
|
**Learning Objectives**:
|
||||||
|
- Implement common list operations (indexing, slicing, concatenation)
|
||||||
|
- Analyze time complexity of list methods (append, insert, pop)
|
||||||
|
- Apply list comprehensions for data transformation
|
||||||
|
|
||||||
|
**Topics Covered**:
|
||||||
|
- List creation and initialization
|
||||||
|
- Indexing and slicing operations
|
||||||
|
- Common methods (append, extend, insert, remove, pop)
|
||||||
|
- List comprehensions and filtering
|
||||||
|
- Performance characteristics (O(1) append vs O(n) insert)
|
||||||
|
|
||||||
|
**Tutorials/Exercises**:
|
||||||
|
- Build a shopping cart system using lists
|
||||||
|
- Implement a simple task manager
|
||||||
|
- Performance comparison exercises
|
||||||
|
|
||||||
|
**Code Examples**:
|
||||||
|
- list-basics.py - Basic operations
|
||||||
|
- list-comprehensions.py - Advanced filtering
|
||||||
|
- list-performance.py - Benchmark different operations
|
||||||
|
|
||||||
|
**Estimated Pages**: 25-30
|
||||||
|
**Prerequisites**: None (first chapter)
|
||||||
|
**Difficulty**: Beginner
|
||||||
|
|
||||||
|
### Chapter 2: Dictionary Mastery
|
||||||
|
|
||||||
|
**Learning Objectives**:
|
||||||
|
- Implement dictionary operations for key-value storage
|
||||||
|
- Evaluate when to use dictionaries vs other structures
|
||||||
|
- Create nested dictionaries for complex data
|
||||||
|
|
||||||
|
**Topics Covered**:
|
||||||
|
- Dictionary creation and access patterns
|
||||||
|
- Common methods (get, keys, values, items)
|
||||||
|
- Dictionary comprehensions
|
||||||
|
- Handling missing keys (defaultdict, get method)
|
||||||
|
- Nested dictionaries and JSON-like structures
|
||||||
|
|
||||||
|
**Tutorials/Exercises**:
|
||||||
|
- Build a contact management system
|
||||||
|
- Parse and transform JSON data
|
||||||
|
- Implement a caching system
|
||||||
|
|
||||||
|
**Code Examples**:
|
||||||
|
- dict-operations.py - Core operations
|
||||||
|
- dict-advanced.py - Nested structures
|
||||||
|
- dict-performance.py - Hash table performance
|
||||||
|
|
||||||
|
**Estimated Pages**: 30-35
|
||||||
|
**Prerequisites**: Chapter 1
|
||||||
|
**Difficulty**: Beginner
|
||||||
|
|
||||||
|
[... Continues for remaining 10 chapters ...]
|
||||||
|
|
||||||
|
## Learning Path Progression
|
||||||
|
|
||||||
|
**Beginner (Chapters 1-5)**: Built-in data structures with clear tutorials
|
||||||
|
- Remember: Recall syntax and methods
|
||||||
|
- Understand: Explain when to use each structure
|
||||||
|
- Apply: Implement in practice exercises
|
||||||
|
|
||||||
|
**Intermediate (Chapters 6-9)**: Custom implementations
|
||||||
|
- Analyze: Compare time/space complexity
|
||||||
|
- Evaluate: Choose optimal structures
|
||||||
|
- Create: Build custom data structures
|
||||||
|
|
||||||
|
**Advanced (Chapters 10-12)**: Real-world optimization
|
||||||
|
- Optimize: Performance tuning
|
||||||
|
- Design: System architecture decisions
|
||||||
|
|
||||||
|
## Back Matter Plan
|
||||||
|
|
||||||
|
**Appendix A**: Big-O Complexity Reference (Quick lookup table)
|
||||||
|
**Appendix B**: Python 3.11+ New Features (Relevant to data structures)
|
||||||
|
**Appendix C**: Performance Benchmarking Tools
|
||||||
|
|
||||||
|
**Glossary**: ~50 terms (amortized complexity, hash collision, etc.)
|
||||||
|
**Index**: Focus on data structures, methods, performance topics
|
||||||
|
|
||||||
|
## Code Repository Plan
|
||||||
|
|
||||||
|
```
|
||||||
|
python-data-structures-handbook/
|
||||||
|
├── README.md (Installation, testing instructions)
|
||||||
|
├── chapter-01/ (List fundamentals)
|
||||||
|
│ ├── list-basics.py
|
||||||
|
│ ├── list-comprehensions.py
|
||||||
|
│ ├── tests/
|
||||||
|
├── chapter-02/ (Dictionaries)
|
||||||
|
│ ├── dict-operations.py
|
||||||
|
│ ├── dict-advanced.py
|
||||||
|
│ ├── tests/
|
||||||
|
[... continues ...]
|
||||||
|
├── .github/workflows/test.yml (CI/CD)
|
||||||
|
├── requirements.txt (Python 3.11+, pytest)
|
||||||
|
└── Makefile (test, lint commands)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Testing Strategy**: Unit tests for all code examples, pytest framework
|
||||||
|
**Version Support**: Python 3.11+
|
||||||
|
**CI/CD**: GitHub Actions runs tests on 3.11, 3.12
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Book Proposal Template
|
||||||
|
|
||||||
|
**ID**: `book-proposal-tmpl.yaml`
|
||||||
|
**Purpose**: Creates comprehensive publisher proposal with market analysis
|
||||||
|
**Related Workflows**: Book Planning Workflow
|
||||||
|
**Related Agents**: book-publisher
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Chapter Outline Template
|
||||||
|
|
||||||
|
**ID**: `chapter-outline-tmpl.yaml`
|
||||||
|
**Output**: `chapter-{n}-outline.md`
|
||||||
|
**Elicitation**: Required
|
||||||
|
|
||||||
|
#### Purpose
|
||||||
|
|
||||||
|
Creates detailed single chapter structure with learning objectives, sections, exercises, and code examples. Used before writing chapter content.
|
||||||
|
|
||||||
|
#### Sample Output (Excerpt)
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Chapter 3: Set Operations and Applications
|
||||||
|
|
||||||
|
## Chapter Metadata
|
||||||
|
|
||||||
|
**Chapter Number**: 3
|
||||||
|
**Estimated Pages**: 28-32
|
||||||
|
**Time to Complete**: 2-3 hours
|
||||||
|
**Difficulty**: Intermediate
|
||||||
|
**Part**: Part I - Built-in Data Structures
|
||||||
|
|
||||||
|
## Learning Objectives
|
||||||
|
|
||||||
|
1. **Implement** set operations (union, intersection, difference, symmetric difference)
|
||||||
|
2. **Analyze** when sets provide performance advantages over lists
|
||||||
|
3. **Apply** sets to solve duplicate detection and membership testing problems
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
- Chapter 1: List Fundamentals (completed)
|
||||||
|
- Chapter 2: Dictionary Mastery (completed)
|
||||||
|
- Understanding of hash tables (covered in Chapter 2)
|
||||||
|
- Python 3.11+ installed with pytest
|
||||||
|
|
||||||
|
## Introduction Section
|
||||||
|
|
||||||
|
**Hook**: "Have you ever needed to find unique users across multiple datasets, or check if an element exists in a collection instantly? Sets are Python's secret weapon for these scenarios."
|
||||||
|
|
||||||
|
**Overview**: This chapter explores Python sets—unordered collections optimized for membership testing and eliminating duplicates. We'll implement mathematical set operations, compare performance against lists, and build practical applications.
|
||||||
|
|
||||||
|
**Real-World Use Cases**:
|
||||||
|
- Deduplicating data streams
|
||||||
|
- Access control (checking user permissions)
|
||||||
|
- Finding common elements across datasets
|
||||||
|
- Graph algorithms (tracking visited nodes)
|
||||||
|
|
||||||
|
## Main Content Sections
|
||||||
|
|
||||||
|
### Section 1: Set Fundamentals (6-7 pages)
|
||||||
|
- Set creation and initialization
|
||||||
|
- Add, remove, discard methods
|
||||||
|
- Membership testing with `in` operator
|
||||||
|
- Performance: O(1) lookup vs O(n) list search
|
||||||
|
- **Code**: `set-basics.py` - Core operations
|
||||||
|
- **Diagram**: Hash table visualization
|
||||||
|
|
||||||
|
### Section 2: Set Operations (8-10 pages)
|
||||||
|
- Union, intersection, difference, symmetric difference
|
||||||
|
- Operator syntax (|, &, -, ^) vs method syntax
|
||||||
|
- Subset and superset testing
|
||||||
|
- **Code**: `set-operations.py` - Mathematical operations
|
||||||
|
- **Tutorial**: Building a permission system with sets
|
||||||
|
|
||||||
|
### Section 3: Practical Applications (8-10 pages)
|
||||||
|
- Deduplication strategies
|
||||||
|
- Fast membership testing
|
||||||
|
- Set comprehensions
|
||||||
|
- Frozen sets for immutability
|
||||||
|
- **Code**: `set-applications.py` - Real-world examples
|
||||||
|
- **Tutorial**: Finding common followers across social networks
|
||||||
|
|
||||||
|
## Exercises & Challenges
|
||||||
|
|
||||||
|
**Guided Exercises**:
|
||||||
|
1. Implement user access control (15 min)
|
||||||
|
2. Deduplicate log entries (20 min)
|
||||||
|
3. Find common items in shopping carts (15 min)
|
||||||
|
|
||||||
|
**Challenge Problems**:
|
||||||
|
1. Optimize a slow list-based search (30 min)
|
||||||
|
2. Build a simple graph traversal using sets (45 min)
|
||||||
|
|
||||||
|
**Solutions**: Hints provided in appendix, full solutions in repository
|
||||||
|
|
||||||
|
## Code Files List
|
||||||
|
|
||||||
|
- `set-basics.py` - Set creation and core operations (Python 3.11+)
|
||||||
|
- `set-operations.py` - Mathematical set operations
|
||||||
|
- `set-applications.py` - Practical examples (deduplication, permissions)
|
||||||
|
- `tests/test_sets.py` - Unit tests for all examples
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Chapter Content Templates
|
||||||
|
|
||||||
|
### Section Plan Template
|
||||||
|
|
||||||
|
**ID**: `section-plan-tmpl.yaml`
|
||||||
|
**Output**: `section-{n}.md`
|
||||||
|
**Elicitation**: Not required (filled by agent)
|
||||||
|
|
||||||
|
#### Purpose
|
||||||
|
|
||||||
|
Defines one deliverable section (2-5 pages) with acceptance criteria. This is the "story" unit of section-driven development, enabling incremental chapter progress tracking.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Breaking chapter into work units
|
||||||
|
- Using section-driven development workflow
|
||||||
|
- Want clear "DONE" criteria for each section
|
||||||
|
- Tracking incremental progress ("5 of 8 sections complete")
|
||||||
|
|
||||||
|
#### Sample Output
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Section Plan: Section 3.2 - Set Operations
|
||||||
|
|
||||||
|
## Section Metadata
|
||||||
|
|
||||||
|
**Section ID**: section-3.2
|
||||||
|
**Section Title**: Mathematical Set Operations
|
||||||
|
**Chapter**: Chapter 3 - Set Operations and Applications
|
||||||
|
**Position**: 2 of 3 sections
|
||||||
|
**Estimated Pages**: 8-10 pages
|
||||||
|
**Story Points**: 5 (Medium)
|
||||||
|
|
||||||
|
## Learning Objective
|
||||||
|
|
||||||
|
**Implement mathematical set operations (union, intersection, difference, symmetric difference) using both operator and method syntax to solve data comparison problems.**
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
- Section 3.1: Set Fundamentals (completed - introduces sets and basic operations)
|
||||||
|
- Understanding of mathematical set theory (brief review will be provided)
|
||||||
|
- Code from section 3.1 (set-basics.py) for comparison examples
|
||||||
|
|
||||||
|
## Content Plan
|
||||||
|
|
||||||
|
**Main Concept**: Python sets support mathematical operations that mirror set theory. Readers will learn to combine, compare, and manipulate sets using intuitive operators.
|
||||||
|
|
||||||
|
**Key Points**:
|
||||||
|
- Union (|): Combines all elements from multiple sets
|
||||||
|
- Intersection (&): Finds common elements
|
||||||
|
- Difference (-): Elements in one set but not another
|
||||||
|
- Symmetric difference (^): Elements in either set but not both
|
||||||
|
- Operator syntax vs method syntax (when to use each)
|
||||||
|
|
||||||
|
**Tutorial Approach**: Example-driven with permission system case study
|
||||||
|
|
||||||
|
**Estimated Breakdown**:
|
||||||
|
- Concept explanation: 2-3 pages (introduce each operation)
|
||||||
|
- Tutorial walkthrough: 4-5 pages (build permission system)
|
||||||
|
- Practice exercises: 2 pages (guided problems)
|
||||||
|
|
||||||
|
## Code Examples Needed
|
||||||
|
|
||||||
|
**Example 1**: `set-operations-basic.py` - Demonstrates all four operations
|
||||||
|
- Purpose: Show syntax and output for each operation
|
||||||
|
- Complexity: Simple
|
||||||
|
- Input: Predefined sets of users/roles
|
||||||
|
- Expected Output: Visual results of each operation
|
||||||
|
|
||||||
|
**Example 2**: `permission-system.py` - Permission checking application
|
||||||
|
- Purpose: Real-world use case for set operations
|
||||||
|
- Complexity: Medium
|
||||||
|
- Demonstrates: Union for combining permissions, intersection for shared access
|
||||||
|
- Testing: Unit tests for each permission scenario
|
||||||
|
|
||||||
|
## Success Criteria
|
||||||
|
|
||||||
|
This section is **DONE** when:
|
||||||
|
- [x] All four set operations explained clearly with examples
|
||||||
|
- [x] Operator vs method syntax comparison provided
|
||||||
|
- [x] Permission system tutorial complete and tested
|
||||||
|
- [x] Code examples developed and all tests passing
|
||||||
|
- [x] Section length 8-10 pages (not too verbose)
|
||||||
|
- [x] Transitions from section 3.1 and to section 3.3 clear
|
||||||
|
- [x] Technical reviewer approved accuracy
|
||||||
|
- [x] No security issues in permission example code
|
||||||
|
- [x] Performance note: O(min(len(s), len(t))) for intersection included
|
||||||
|
|
||||||
|
## Dependencies
|
||||||
|
|
||||||
|
**Must complete before starting**:
|
||||||
|
- section-3.1 (Set Fundamentals - need basic knowledge)
|
||||||
|
|
||||||
|
**Can develop in parallel with**:
|
||||||
|
- section-3.3 (Practical Applications - different focus)
|
||||||
|
|
||||||
|
**Blocks**:
|
||||||
|
- section-3.3 (builds on these operations for real-world examples)
|
||||||
|
|
||||||
|
## Development Notes
|
||||||
|
|
||||||
|
**Key Resources**:
|
||||||
|
- Python official docs: set methods
|
||||||
|
- Real-world inspiration: Unix file permissions, RBAC systems
|
||||||
|
|
||||||
|
**Complexity Areas**:
|
||||||
|
- Symmetric difference is less intuitive - use Venn diagram
|
||||||
|
- Method syntax has update variants (union vs update) - clarify in-place vs new set
|
||||||
|
|
||||||
|
**Reader Perspective**:
|
||||||
|
- Most readers familiar with union/intersection from SQL
|
||||||
|
- Connect to real use cases early (don't stay abstract)
|
||||||
|
|
||||||
|
**Special Attention**:
|
||||||
|
- Permission example must demonstrate security best practices
|
||||||
|
- Performance implications: when operations matter for large sets
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Chapter Draft Template
|
||||||
|
|
||||||
|
**ID**: `chapter-draft-tmpl.yaml`
|
||||||
|
**Purpose**: Full chapter draft structure with sections, examples, exercises
|
||||||
|
**Related Workflows**: Chapter Development Workflow (traditional approach)
|
||||||
|
**Related Agents**: tutorial-architect
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Introduction Template
|
||||||
|
|
||||||
|
**ID**: `introduction-tmpl.yaml`
|
||||||
|
**Purpose**: Book introduction/opening chapter
|
||||||
|
**Related Agents**: book-publisher, tutorial-architect
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Preface Template
|
||||||
|
|
||||||
|
**ID**: `preface-tmpl.yaml`
|
||||||
|
**Purpose**: Book preface (author voice, how to use book)
|
||||||
|
**Related Agents**: book-publisher
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Appendix Template
|
||||||
|
|
||||||
|
**ID**: `appendix-tmpl.yaml`
|
||||||
|
**Purpose**: Reference appendices
|
||||||
|
**Related Agents**: api-documenter
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Code Templates
|
||||||
|
|
||||||
|
### Code Example Template
|
||||||
|
|
||||||
|
**ID**: `code-example-tmpl.yaml`
|
||||||
|
**Purpose**: Tested code example with documentation
|
||||||
|
**Related Workflows**: Code Example Workflow
|
||||||
|
**Related Agents**: code-curator
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### API Reference Template
|
||||||
|
|
||||||
|
**ID**: `api-reference-tmpl.yaml`
|
||||||
|
**Purpose**: Comprehensive API documentation with parameters, returns, examples
|
||||||
|
**Related Workflows**: Tutorial Creation, Chapter Development
|
||||||
|
**Related Agents**: api-documenter
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Learning Templates
|
||||||
|
|
||||||
|
### Learning Objectives Template
|
||||||
|
|
||||||
|
**ID**: `learning-objectives-tmpl.yaml`
|
||||||
|
**Purpose**: Measurable learning outcomes using Bloom's taxonomy
|
||||||
|
**Related Agents**: instructional-designer
|
||||||
|
|
||||||
|
#### Sample Output
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Learning Objectives: Chapter 5 - Advanced Dictionary Techniques
|
||||||
|
|
||||||
|
## Objectives
|
||||||
|
|
||||||
|
By the end of this chapter, you will be able to:
|
||||||
|
|
||||||
|
1. **Create** custom dictionary classes that extend built-in functionality for specialized use cases
|
||||||
|
|
||||||
|
2. **Implement** advanced dictionary patterns (defaultdict, Counter, ChainMap) to simplify complex data handling
|
||||||
|
|
||||||
|
3. **Analyze** dictionary performance characteristics to choose optimal implementations for large datasets
|
||||||
|
|
||||||
|
4. **Evaluate** when to use dictionaries vs other data structures based on access patterns and memory constraints
|
||||||
|
|
||||||
|
5. **Design** caching systems using dictionaries with LRU eviction strategies
|
||||||
|
|
||||||
|
## Bloom's Taxonomy Levels
|
||||||
|
|
||||||
|
- **Create** (Level 6): Custom dictionary classes, caching systems
|
||||||
|
- **Evaluate** (Level 5): Structure selection, trade-off analysis
|
||||||
|
- **Analyze** (Level 4): Performance characteristics, access patterns
|
||||||
|
- **Implement** (Level 3): Advanced patterns (defaultdict, Counter)
|
||||||
|
|
||||||
|
## Measurability
|
||||||
|
|
||||||
|
Each objective maps to specific exercises:
|
||||||
|
- Objective 1 → Exercise 5.3: Build OrderedCache class
|
||||||
|
- Objective 2 → Exercise 5.1: Implement word counter with defaultdict
|
||||||
|
- Objective 3 → Exercise 5.4: Benchmark dictionary vs list performance
|
||||||
|
- Objective 4 → Exercise 5.2: Compare structures for user session storage
|
||||||
|
- Objective 5 → Exercise 5.5: Create LRU cache decorator
|
||||||
|
|
||||||
|
## Alignment
|
||||||
|
|
||||||
|
- **Book-Level**: Advances toward "Choose optimal data structures" outcome
|
||||||
|
- **Part-Level**: Completes Part I mastery of built-in structures
|
||||||
|
- **Next Chapter**: Prerequisite for Chapter 6 custom data structures
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Exercise Set Template
|
||||||
|
|
||||||
|
**ID**: `exercise-set-tmpl.yaml`
|
||||||
|
**Purpose**: Practice problems with solutions and difficulty levels
|
||||||
|
**Related Agents**: exercise-creator
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tutorial Templates
|
||||||
|
|
||||||
|
### Tutorial Section Template
|
||||||
|
|
||||||
|
**ID**: `tutorial-section-tmpl.yaml`
|
||||||
|
**Purpose**: Step-by-step hands-on tutorial section
|
||||||
|
**Related Workflows**: Tutorial Creation Workflow
|
||||||
|
**Related Agents**: tutorial-architect
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Review Templates
|
||||||
|
|
||||||
|
### Technical Review Report Template
|
||||||
|
|
||||||
|
**ID**: `technical-review-report-tmpl.yaml`
|
||||||
|
**Purpose**: Structured technical review findings with severity levels
|
||||||
|
**Related Workflows**: Technical Review Workflow
|
||||||
|
**Related Agents**: technical-reviewer
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Revision Plan Template
|
||||||
|
|
||||||
|
**ID**: `revision-plan-tmpl.yaml`
|
||||||
|
**Purpose**: Strategic plan for book updates/revisions
|
||||||
|
**Related Workflows**: Book Edition Update Workflow
|
||||||
|
**Related Agents**: book-analyst
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Visual Templates
|
||||||
|
|
||||||
|
### Diagram Specification Template
|
||||||
|
|
||||||
|
**ID**: `diagram-spec-tmpl.yaml`
|
||||||
|
**Purpose**: Technical diagram specifications (Mermaid, architecture diagrams)
|
||||||
|
**Related Agents**: screenshot-specialist
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Documentation Templates
|
||||||
|
|
||||||
|
### Glossary Entry Template
|
||||||
|
|
||||||
|
**ID**: `glossary-entry-tmpl.yaml`
|
||||||
|
**Purpose**: Consistent glossary term definitions
|
||||||
|
**Related Agents**: api-documenter
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Book Analysis Report Template
|
||||||
|
|
||||||
|
**ID**: `book-analysis-report-tmpl.yaml`
|
||||||
|
**Purpose**: Analysis of existing book for revision planning
|
||||||
|
**Related Workflows**: Book Edition Update Workflow
|
||||||
|
**Related Agents**: book-analyst
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Template Comparison Table
|
||||||
|
|
||||||
|
| Template | Category | Elicit? | Primary Agent | Use Case |
|
||||||
|
|----------|----------|---------|---------------|----------|
|
||||||
|
| book-outline-tmpl | Planning | Yes | instructional-designer | Book planning |
|
||||||
|
| book-proposal-tmpl | Planning | Yes | book-publisher | Publisher proposals |
|
||||||
|
| chapter-outline-tmpl | Planning | Yes | tutorial-architect | Chapter planning |
|
||||||
|
| section-plan-tmpl | Chapter Content | No | tutorial-architect | Section-driven development |
|
||||||
|
| chapter-draft-tmpl | Chapter Content | Yes | tutorial-architect | Full chapter drafts |
|
||||||
|
| introduction-tmpl | Chapter Content | Yes | book-publisher/tutorial-architect | Book introductions |
|
||||||
|
| preface-tmpl | Chapter Content | Yes | book-publisher | Book prefaces |
|
||||||
|
| appendix-tmpl | Chapter Content | No | api-documenter | Reference appendices |
|
||||||
|
| code-example-tmpl | Code | No | code-curator | Tested code examples |
|
||||||
|
| api-reference-tmpl | Code | No | api-documenter | API documentation |
|
||||||
|
| learning-objectives-tmpl | Learning | Yes | instructional-designer | Learning outcomes |
|
||||||
|
| exercise-set-tmpl | Learning | Yes | exercise-creator | Practice problems |
|
||||||
|
| tutorial-section-tmpl | Tutorial | Yes | tutorial-architect | Hands-on tutorials |
|
||||||
|
| technical-review-report-tmpl | Review | No | technical-reviewer | Technical reviews |
|
||||||
|
| revision-plan-tmpl | Review | No | book-analyst | Update planning |
|
||||||
|
| diagram-spec-tmpl | Visual | No | screenshot-specialist | Technical diagrams |
|
||||||
|
| glossary-entry-tmpl | Documentation | No | api-documenter | Glossaries |
|
||||||
|
| book-analysis-report-tmpl | Documentation | No | book-analyst | Book analysis |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Template Selection Guide
|
||||||
|
|
||||||
|
**I want to...**
|
||||||
|
|
||||||
|
### Plan a book
|
||||||
|
→ `book-outline-tmpl` - Complete book structure
|
||||||
|
→ `book-proposal-tmpl` - Publisher submission
|
||||||
|
|
||||||
|
### Plan a chapter
|
||||||
|
→ `chapter-outline-tmpl` - Detailed chapter structure
|
||||||
|
→ `section-plan-tmpl` - Break into deliverable sections
|
||||||
|
|
||||||
|
### Write content
|
||||||
|
→ `chapter-draft-tmpl` - Full chapter (traditional approach)
|
||||||
|
→ `tutorial-section-tmpl` - Hands-on tutorials
|
||||||
|
→ `introduction-tmpl` or `preface-tmpl` - Front matter
|
||||||
|
|
||||||
|
### Create code/examples
|
||||||
|
→ `code-example-tmpl` - Tested code snippets
|
||||||
|
→ `api-reference-tmpl` - API documentation
|
||||||
|
|
||||||
|
### Define learning
|
||||||
|
→ `learning-objectives-tmpl` - Measurable outcomes
|
||||||
|
→ `exercise-set-tmpl` - Practice problems
|
||||||
|
|
||||||
|
### Review and revise
|
||||||
|
→ `technical-review-report-tmpl` - Review findings
|
||||||
|
→ `revision-plan-tmpl` - Update strategy
|
||||||
|
→ `book-analysis-report-tmpl` - Existing book analysis
|
||||||
|
|
||||||
|
### Add visuals/extras
|
||||||
|
→ `diagram-spec-tmpl` - Technical diagrams
|
||||||
|
→ `glossary-entry-tmpl` - Terminology
|
||||||
|
→ `appendix-tmpl` - Reference sections
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Customization Notes
|
||||||
|
|
||||||
|
### Variable Substitution
|
||||||
|
|
||||||
|
All templates support variable substitution using `{{variable_name}}` syntax:
|
||||||
|
|
||||||
|
- `{{book_title}}` - Book title
|
||||||
|
- `{{chapter_number}}` - Chapter number
|
||||||
|
- `{{section_number}}` - Section number
|
||||||
|
- `{{author_name}}` - Author name
|
||||||
|
- Custom variables can be defined per template
|
||||||
|
|
||||||
|
### Elicitation Behavior
|
||||||
|
|
||||||
|
- **Elicit=true**: Agent will ask user for input interactively
|
||||||
|
- **Elicit=false**: Agent fills from context automatically
|
||||||
|
- **allow_skip**: Can user skip sections? (typically false)
|
||||||
|
|
||||||
|
### Adapting Templates
|
||||||
|
|
||||||
|
Templates are YAML files - you can:
|
||||||
|
1. Add new sections to existing templates
|
||||||
|
2. Modify section instructions
|
||||||
|
3. Change variable names
|
||||||
|
4. Adjust elicitation behavior
|
||||||
|
5. Create custom templates following same structure
|
||||||
|
|
||||||
|
### Template Format
|
||||||
|
|
||||||
|
All templates follow the BMad Doc Template specification:
|
||||||
|
- `template` block: metadata (id, name, version, description, output format)
|
||||||
|
- `workflow` block: elicitation settings
|
||||||
|
- `sections` array: ordered sections with id, title, instruction, elicit flag
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Conclusion
|
||||||
|
|
||||||
|
The BMad Technical Writing Expansion Pack's **18 templates** provide comprehensive structure for every document type in technical book authoring. By understanding each template's purpose and seeing filled examples, you can:
|
||||||
|
|
||||||
|
- **Create consistent documentation** across your book
|
||||||
|
- **Follow best practices** embedded in template instructions
|
||||||
|
- **Save time** with reusable structures
|
||||||
|
- **Maintain quality** through standardized sections
|
||||||
|
- **Customize** templates for your specific needs
|
||||||
|
|
||||||
|
**Key Templates to Master**:
|
||||||
|
- **book-outline-tmpl** - Foundation of book planning
|
||||||
|
- **chapter-outline-tmpl** - Essential for chapter development
|
||||||
|
- **section-plan-tmpl** - Enables incremental progress
|
||||||
|
- **code-example-tmpl** - Ensures tested code quality
|
||||||
|
|
||||||
|
**Total template count**: 18
|
||||||
|
**Word count**: ~3,200 words
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Related Documentation**:
|
||||||
|
- [Agent Reference Guide](agent-reference.md) - Agents that use these templates
|
||||||
|
- [Workflow Guide](workflow-guide.md) - Workflows that execute templates
|
||||||
|
- [Task Reference](task-reference.md) - Tasks that invoke templates
|
||||||
|
- [User Guide](user-guide.md) - How templates fit into the process
|
||||||
|
|
@ -0,0 +1,847 @@
|
||||||
|
# Workflow Guide
|
||||||
|
|
||||||
|
## Introduction
|
||||||
|
|
||||||
|
The BMad Technical Writing Expansion Pack provides **15 specialized workflows** that orchestrate the entire technical book authoring lifecycle. Each workflow defines a complete process with agent sequences, quality gates, time estimates, and decision guidance.
|
||||||
|
|
||||||
|
This comprehensive guide documents all 15 workflows organized by category, with detailed information about:
|
||||||
|
|
||||||
|
- **Purpose** - What the workflow accomplishes
|
||||||
|
- **When to use** - Specific scenarios where this workflow is most effective
|
||||||
|
- **Inputs required** - Prerequisites and files needed to start
|
||||||
|
- **Outputs produced** - Deliverables created by the workflow
|
||||||
|
- **Agents involved** - Primary and supporting agents in sequence
|
||||||
|
- **Estimated time** - Typical duration from workflow YAML
|
||||||
|
- **Step-by-step breakdown** - Complete workflow sequence
|
||||||
|
- **Quality gates** - Checkpoints and validation criteria
|
||||||
|
|
||||||
|
### Workflow Categories
|
||||||
|
|
||||||
|
- **Planning (1)**: Book concept to approved outline
|
||||||
|
- **Development (6)**: Chapter creation, section-driven approach, tutorials, code examples
|
||||||
|
- **Review (2)**: Technical validation and incorporating feedback
|
||||||
|
- **Publishing (4)**: Publisher-specific formatting and submission
|
||||||
|
- **Brownfield (2)**: Updating existing books and adding chapters
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Planning Workflows
|
||||||
|
|
||||||
|
### Book Planning Workflow
|
||||||
|
|
||||||
|
**ID**: `book-planning-workflow`
|
||||||
|
**Type**: book-planning
|
||||||
|
**Version**: 1.0
|
||||||
|
|
||||||
|
#### Purpose
|
||||||
|
|
||||||
|
Complete book planning from concept to approved outline. Guides technical authors through proposal creation, outline design, learning path validation, editorial review, and publisher requirements verification. Ensures pedagogical soundness and publisher compliance before chapter development begins.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Planning a new technical book from scratch
|
||||||
|
- Pitching book proposal to publisher
|
||||||
|
- Need structured approach to outline creation
|
||||||
|
- Want to validate pedagogical design before writing
|
||||||
|
- Working with traditional publisher with specific requirements
|
||||||
|
|
||||||
|
#### When NOT to Use
|
||||||
|
|
||||||
|
- Book outline already approved (jump to chapter development)
|
||||||
|
- Self-publishing without strict format requirements
|
||||||
|
- Converting existing content to book (use revision workflow)
|
||||||
|
|
||||||
|
#### Inputs Required
|
||||||
|
|
||||||
|
- Book topic
|
||||||
|
- Target audience
|
||||||
|
- Publisher (optional)
|
||||||
|
|
||||||
|
#### Outputs Produced
|
||||||
|
|
||||||
|
- `book-proposal.md` - Comprehensive proposal with market analysis
|
||||||
|
- `book-outline.md` - Detailed pedagogical outline
|
||||||
|
- `learning-path-validation.md` - Prerequisite flow validation
|
||||||
|
- `book-outline-edited.md` - Editorially polished outline
|
||||||
|
- `book-outline-final.md` - Publisher-approved outline
|
||||||
|
|
||||||
|
#### Agents Involved (Sequence)
|
||||||
|
|
||||||
|
1. **book-publisher** - Drafts comprehensive book proposal
|
||||||
|
2. **instructional-designer** - Creates detailed pedagogical outline
|
||||||
|
3. **instructional-designer** - Validates learning progression
|
||||||
|
4. **technical-editor** - Reviews for clarity and consistency
|
||||||
|
5. **book-publisher** - Verifies publisher requirements
|
||||||
|
|
||||||
|
#### Estimated Time
|
||||||
|
|
||||||
|
- Draft proposal: 4-8 hours
|
||||||
|
- Design outline: 8-12 hours
|
||||||
|
- Validate learning path: 3-5 hours
|
||||||
|
- Editorial review: 3-5 hours
|
||||||
|
- Publisher format check: 2-3 hours
|
||||||
|
- **Total**: 20-33 hours for complete book planning
|
||||||
|
|
||||||
|
#### Step-by-Step Breakdown
|
||||||
|
|
||||||
|
1. **Draft Proposal** (`book-publisher`)
|
||||||
|
- Creates `book-proposal.md` using `book-proposal-tmpl.yaml`
|
||||||
|
- Includes: market analysis, competitive titles, target audience profile, unique value proposition, chapter list, author platform, timeline
|
||||||
|
- Save to: `docs/planning/book-proposal.md`
|
||||||
|
|
||||||
|
2. **Design Outline** (`instructional-designer`)
|
||||||
|
- Creates `book-outline.md` using `book-outline-tmpl.yaml`
|
||||||
|
- Defines: learning progression, prerequisites per chapter, topics/subtopics, exercise strategy, difficulty curve
|
||||||
|
- Ensures pedagogical soundness and logical skill building
|
||||||
|
- Save to: `docs/planning/book-outline.md`
|
||||||
|
|
||||||
|
3. **Validate Learning Path** (`instructional-designer`)
|
||||||
|
- Validates prerequisite flow ensures no knowledge gaps
|
||||||
|
- Checks concepts build logically chapter by chapter
|
||||||
|
- Verifies exercises progress from basic to advanced
|
||||||
|
- Uses `learning-objectives-checklist.md` and `prerequisite-clarity-checklist.md`
|
||||||
|
- Save to: `docs/planning/learning-path-validation.md`
|
||||||
|
|
||||||
|
4. **Editorial Review** (`technical-editor`)
|
||||||
|
- Reviews outline for clarity, consistency, professional quality
|
||||||
|
- Checks chapter titles are clear and compelling
|
||||||
|
- Ensures terminology is consistent
|
||||||
|
- Verifies structure follows publisher best practices
|
||||||
|
- Save to: `docs/planning/book-outline-edited.md`
|
||||||
|
|
||||||
|
5. **Publisher Format Check** (`book-publisher`)
|
||||||
|
- Verifies outline matches publisher chapter count guidelines
|
||||||
|
- Checks technical depth appropriate for series/imprint
|
||||||
|
- Ensures format follows publisher template
|
||||||
|
- Confirms timeline is realistic
|
||||||
|
- Uses publisher-specific checklist (PacktPub, O'Reilly, or Manning)
|
||||||
|
- Save to: `docs/planning/book-outline-final.md`
|
||||||
|
- **Status**: Ready for Chapter Development
|
||||||
|
|
||||||
|
#### Quality Gates
|
||||||
|
|
||||||
|
**Proposal Complete:**
|
||||||
|
- Market analysis included
|
||||||
|
- Target audience clearly defined
|
||||||
|
- Competitive titles identified
|
||||||
|
- Unique value proposition stated
|
||||||
|
- High-level chapter list provided
|
||||||
|
- Author platform described
|
||||||
|
- Realistic timeline included
|
||||||
|
|
||||||
|
**Outline Complete:**
|
||||||
|
- All chapters have clear titles
|
||||||
|
- Learning objectives defined for each chapter
|
||||||
|
- Prerequisites stated for each chapter
|
||||||
|
- Topics and subtopics outlined
|
||||||
|
- Exercise strategy defined
|
||||||
|
- Estimated page counts provided
|
||||||
|
|
||||||
|
**Learning Path Validated:**
|
||||||
|
- No knowledge gaps between chapters
|
||||||
|
- Difficulty curve is smooth
|
||||||
|
- Prerequisites are achievable
|
||||||
|
- Exercises progress appropriately
|
||||||
|
- Reader can succeed with stated background
|
||||||
|
|
||||||
|
**Editorial Complete:**
|
||||||
|
- Chapter titles are compelling
|
||||||
|
- No topic duplication
|
||||||
|
- Terminology consistent throughout
|
||||||
|
- Structure follows best practices
|
||||||
|
|
||||||
|
**Publisher Approved:**
|
||||||
|
- Chapter count matches guidelines
|
||||||
|
- Technical depth appropriate
|
||||||
|
- Format matches publisher template
|
||||||
|
- Timeline is realistic
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Development Workflows
|
||||||
|
|
||||||
|
### Chapter Development Workflow (v2.0 - Section-Driven)
|
||||||
|
|
||||||
|
**ID**: `chapter-development-workflow`
|
||||||
|
**Type**: chapter-writing
|
||||||
|
**Version**: 2.0
|
||||||
|
|
||||||
|
#### Purpose
|
||||||
|
|
||||||
|
Complete chapter creation 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.
|
||||||
|
|
||||||
|
#### When to Use Section-Driven Approach
|
||||||
|
|
||||||
|
- 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 Approach
|
||||||
|
|
||||||
|
- Short chapters (<10-12 pages)
|
||||||
|
- Simple reference sections
|
||||||
|
- Author prefers writing full chapter at once
|
||||||
|
- Chapter already partially written
|
||||||
|
|
||||||
|
#### Inputs Required
|
||||||
|
|
||||||
|
- `book-outline.md` - Approved book outline
|
||||||
|
|
||||||
|
#### Outputs Produced (Section-Driven)
|
||||||
|
|
||||||
|
- `chapter-outline.md` - Detailed chapter outline
|
||||||
|
- `section-list.md` - List of all section plans
|
||||||
|
- `section-{n}-final.md` - Each completed section
|
||||||
|
- `chapter-integrated.md` - Merged chapter
|
||||||
|
- `chapter-final.md` - Publisher-ready chapter
|
||||||
|
|
||||||
|
#### Agents Involved (Section-Driven Sequence)
|
||||||
|
|
||||||
|
1. **tutorial-architect** - Creates chapter outline
|
||||||
|
2. **tutorial-architect** → **section-planning-workflow** - Plans 5-8 sections
|
||||||
|
3. **tutorial-architect** → **section-development-workflow** - Develops each section
|
||||||
|
4. **tutorial-architect** → **chapter-assembly-workflow** - Assembles chapter
|
||||||
|
5. **tutorial-architect** - Final validation
|
||||||
|
|
||||||
|
#### Estimated Time
|
||||||
|
|
||||||
|
**Section-Driven Approach:**
|
||||||
|
- Create outline: 2-4 hours
|
||||||
|
- Plan sections: 6-11 hours
|
||||||
|
- Develop sections: 33-84 hours (can be parallel)
|
||||||
|
- Assemble chapter: 13-24 hours
|
||||||
|
- **Total**: 54-123 hours per chapter (parallel development possible)
|
||||||
|
|
||||||
|
**Traditional Approach:**
|
||||||
|
- Create outline: 2-4 hours
|
||||||
|
- Develop code: 4-8 hours
|
||||||
|
- Write draft: 12-20 hours
|
||||||
|
- Technical review: 3-5 hours
|
||||||
|
- Revision: 4-8 hours
|
||||||
|
- Copy edit: 2-4 hours
|
||||||
|
- Finalization: 1-2 hours
|
||||||
|
- **Total**: 28-51 hours per chapter (sequential)
|
||||||
|
|
||||||
|
**Comparison**: Section-driven has higher total time but allows parallel work and incremental progress. Traditional is faster for solo authors on short chapters.
|
||||||
|
|
||||||
|
#### Step-by-Step Breakdown (Section-Driven)
|
||||||
|
|
||||||
|
1. **Create Chapter Outline** (`tutorial-architect`)
|
||||||
|
- Defines learning objectives, prerequisites, main sections, exercises, code examples
|
||||||
|
- Uses `create-chapter-outline.md` task
|
||||||
|
- Save to: `docs/outlines/chapter-{n}-outline.md`
|
||||||
|
|
||||||
|
2. **Plan Sections** (`tutorial-architect` → **section-planning-workflow**)
|
||||||
|
- Breaks chapter into 5-8 deliverable sections (2-5 pages each)
|
||||||
|
- Creates section plans with clear acceptance criteria
|
||||||
|
- Validates learning flow across sections
|
||||||
|
- Save to: `docs/sections/chapter-{n}-section-list.md`
|
||||||
|
|
||||||
|
3. **Develop Sections** (`tutorial-architect` → **section-development-workflow**)
|
||||||
|
- For each section: 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 to: `docs/sections/chapter-{n}/section-{i}-final.md`
|
||||||
|
|
||||||
|
4. **Assemble Chapter** (`tutorial-architect` → **chapter-assembly-workflow**)
|
||||||
|
- Merges all completed sections
|
||||||
|
- Improves transitions between sections
|
||||||
|
- Validates learning flow (Instructional Designer)
|
||||||
|
- Full technical review (Technical Reviewer)
|
||||||
|
- Copy edit (Technical Editor)
|
||||||
|
- Save to: `docs/chapters/chapter-{n}-final.md`
|
||||||
|
|
||||||
|
5. **Final Validation** (`tutorial-architect`)
|
||||||
|
- Runs `chapter-completeness-checklist.md`
|
||||||
|
- Verifies all learning objectives addressed
|
||||||
|
- **Status**: Ready for Publication
|
||||||
|
|
||||||
|
#### Quality Gates
|
||||||
|
|
||||||
|
**Outline Complete:**
|
||||||
|
- Learning objectives defined (3-5)
|
||||||
|
- Prerequisites clearly stated
|
||||||
|
- All code examples identified
|
||||||
|
- Exercise plan created
|
||||||
|
|
||||||
|
**Sections Complete (each):**
|
||||||
|
- Section meets acceptance criteria
|
||||||
|
- Code tested and working
|
||||||
|
- Learning objectives addressed
|
||||||
|
- 2-5 pages length
|
||||||
|
|
||||||
|
**Chapter Integrated:**
|
||||||
|
- All sections merged
|
||||||
|
- Transitions smooth
|
||||||
|
- Learning flow validated
|
||||||
|
- Full technical review passed
|
||||||
|
- Copy editing complete
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Section Planning Workflow
|
||||||
|
|
||||||
|
**ID**: `section-planning-workflow`
|
||||||
|
**Type**: section-planning
|
||||||
|
|
||||||
|
#### Purpose
|
||||||
|
|
||||||
|
Breaks 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.
|
||||||
|
|
||||||
|
#### 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)
|
||||||
|
|
||||||
|
#### Estimated Time
|
||||||
|
|
||||||
|
- Analyze chapter: 1-2 hours
|
||||||
|
- Identify sections: 1-2 hours
|
||||||
|
- Create section plans: 2-4 hours
|
||||||
|
- Validate flow: 1-2 hours
|
||||||
|
- Finalize list: 1 hour
|
||||||
|
- **Total**: 6-11 hours per chapter
|
||||||
|
|
||||||
|
#### Step-by-Step Breakdown
|
||||||
|
|
||||||
|
1. **Analyze Chapter** (`tutorial-architect`) - Reviews structure, identifies breaking points
|
||||||
|
2. **Identify Sections** (`tutorial-architect`) - Breaks into 5-8 logical sections
|
||||||
|
3. **Create Section Plans** (`tutorial-architect`) - Detailed plan for each section using `section-plan-tmpl.yaml`
|
||||||
|
4. **Validate Flow** (`instructional-designer`) - Validates proper scaffolding, no learning gaps
|
||||||
|
5. **Finalize List** (`tutorial-architect`) - Creates final prioritized section list with dependencies
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Section Development Workflow
|
||||||
|
|
||||||
|
**ID**: `section-development-workflow`
|
||||||
|
**Type**: section-writing
|
||||||
|
|
||||||
|
#### Purpose
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Developing one section from section plan
|
||||||
|
- Incremental chapter development approach
|
||||||
|
- Want focused work units with clear done criteria
|
||||||
|
- Tracking progress section by section
|
||||||
|
|
||||||
|
#### Estimated Time
|
||||||
|
|
||||||
|
- Develop code: 1-2 hours
|
||||||
|
- Test code: 30 min - 1 hour
|
||||||
|
- Write section: 2-4 hours
|
||||||
|
- Technical review: 30 min - 1 hour
|
||||||
|
- Revise section: 1-2 hours
|
||||||
|
- Verify criteria: 30 min
|
||||||
|
- **Total**: 5.5-10.5 hours per section
|
||||||
|
|
||||||
|
#### Step-by-Step Breakdown
|
||||||
|
|
||||||
|
1. **Develop Code** (`code-curator`) - Creates and tests all code examples for section
|
||||||
|
2. **Test Code** (`code-curator`) - Verifies correct output, edge cases, linting
|
||||||
|
3. **Write Section** (`tutorial-architect`) - Writes 2-5 page section with code inline
|
||||||
|
4. **Quick Review** (`technical-reviewer`) - Focused technical review of section
|
||||||
|
5. **Revise** (`tutorial-architect`) - Incorporates review feedback
|
||||||
|
6. **Finalize** (`tutorial-architect`) - Verifies acceptance criteria, marks DONE
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Chapter Assembly Workflow
|
||||||
|
|
||||||
|
**ID**: `chapter-assembly-workflow`
|
||||||
|
**Type**: chapter-integration
|
||||||
|
|
||||||
|
#### Purpose
|
||||||
|
|
||||||
|
Integrates 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.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- All chapter sections marked DONE
|
||||||
|
- Using section-driven development approach
|
||||||
|
- Ready to integrate sections into cohesive chapter
|
||||||
|
- Preparing chapter for publication
|
||||||
|
|
||||||
|
#### Estimated Time
|
||||||
|
|
||||||
|
- Merge sections: 1-2 hours
|
||||||
|
- Improve transitions: 2-3 hours
|
||||||
|
- Validate learning flow: 1-2 hours
|
||||||
|
- Technical review: 3-5 hours
|
||||||
|
- Revise chapter: 3-6 hours
|
||||||
|
- Copy edit: 2-4 hours
|
||||||
|
- Finalize: 1-2 hours
|
||||||
|
- **Total**: 13-24 hours per chapter
|
||||||
|
|
||||||
|
#### Step-by-Step Breakdown
|
||||||
|
|
||||||
|
1. **Merge Sections** (`tutorial-architect`) - Integrates all sections into single file
|
||||||
|
2. **Improve Transitions** (`tutorial-architect`) - Adds bridging paragraphs, cross-references
|
||||||
|
3. **Validate Learning Flow** (`instructional-designer`) - Checks concept progression
|
||||||
|
4. **Full Technical Review** (`technical-reviewer`) - Comprehensive chapter review
|
||||||
|
5. **Revise** (`tutorial-architect`) - Addresses all review feedback
|
||||||
|
6. **Copy Edit** (`technical-editor`) - Professional editorial polish
|
||||||
|
7. **Finalize** (`tutorial-architect`) - Runs completeness checklist, approves edits
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Tutorial Creation Workflow
|
||||||
|
|
||||||
|
**ID**: `tutorial-creation-workflow`
|
||||||
|
**Type**: tutorial-development
|
||||||
|
|
||||||
|
#### Purpose
|
||||||
|
|
||||||
|
Creates effective step-by-step tutorials with tested code and clear instructions. Emphasizes learning objectives, progressive difficulty, and student success.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Creating hands-on coding tutorials
|
||||||
|
- Building step-by-step technical guides
|
||||||
|
- Developing workshop materials
|
||||||
|
- Interactive learning experiences
|
||||||
|
|
||||||
|
#### Estimated Time
|
||||||
|
|
||||||
|
- Design plan: 1-2 hours
|
||||||
|
- Create structure: 2-3 hours
|
||||||
|
- Develop code: 3-6 hours
|
||||||
|
- Write tutorial: 4-8 hours
|
||||||
|
- Test tutorial: 1-2 hours
|
||||||
|
- Revisions: 2-4 hours
|
||||||
|
- Validation: 1-2 hours
|
||||||
|
- Finalization: 30 min - 1 hour
|
||||||
|
- **Total**: 14-28 hours per tutorial
|
||||||
|
|
||||||
|
#### Step-by-Step Breakdown
|
||||||
|
|
||||||
|
1. **Design Learning Path** (`instructional-designer`) - Defines objective, audience, prerequisites
|
||||||
|
2. **Create Structure** (`tutorial-architect`) - 8-15 step progression
|
||||||
|
3. **Develop Code** (`code-curator`) - Creates starter code, complete code, tests
|
||||||
|
4. **Write Tutorial** (`tutorial-architect`) - Complete tutorial with troubleshooting
|
||||||
|
5. **Test End-to-End** (`code-curator`) - Tests in fresh environment
|
||||||
|
6. **Revise** (`tutorial-architect`) - Incorporates testing feedback
|
||||||
|
7. **Validate** (`instructional-designer`) - Checks pedagogical standards
|
||||||
|
8. **Finalize** (`tutorial-architect`) - Ready for students
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Code Example Workflow
|
||||||
|
|
||||||
|
**ID**: `code-example-workflow`
|
||||||
|
**Type**: code-development
|
||||||
|
|
||||||
|
#### Purpose
|
||||||
|
|
||||||
|
Complete code example development from initial code to tested, secure, documented example. Ensures all code examples are production-quality, secure, and well-documented.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Creating code examples for technical books or tutorials
|
||||||
|
- Developing sample applications for documentation
|
||||||
|
- Need production-quality, tested code examples
|
||||||
|
- Security and quality standards must be met
|
||||||
|
|
||||||
|
#### Estimated Time
|
||||||
|
|
||||||
|
- Write code: 1-4 hours
|
||||||
|
- Test code: 1-2 hours
|
||||||
|
- Verify quality: 30 min - 1 hour
|
||||||
|
- Security check: 30 min - 1 hour
|
||||||
|
- Document example: 1-2 hours
|
||||||
|
- **Total**: 4-10 hours per code example
|
||||||
|
|
||||||
|
#### Step-by-Step Breakdown
|
||||||
|
|
||||||
|
1. **Write Code** (`code-curator`) - Clean, idiomatic code with error handling
|
||||||
|
2. **Test** (`code-curator`) - Tests on target platforms and versions
|
||||||
|
3. **Verify Quality** (`code-curator`) - Checks style guide, best practices
|
||||||
|
4. **Security Review** (`code-curator`) - Scans for vulnerabilities
|
||||||
|
5. **Document** (`code-curator`) - Comprehensive README with troubleshooting
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Review Workflows
|
||||||
|
|
||||||
|
### Technical Review Workflow
|
||||||
|
|
||||||
|
**ID**: `technical-review-workflow`
|
||||||
|
**Type**: technical-review
|
||||||
|
|
||||||
|
#### Purpose
|
||||||
|
|
||||||
|
Comprehensive technical validation of chapter content. Verifies technical accuracy, code correctness, security best practices, and current information.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Validating technical accuracy before publication
|
||||||
|
- Ensuring code examples are correct and secure
|
||||||
|
- Checking for outdated or deprecated information
|
||||||
|
- Need expert subject matter review
|
||||||
|
|
||||||
|
#### Estimated Time
|
||||||
|
|
||||||
|
- **Typical**: 3-5 hours per chapter (full review)
|
||||||
|
- **Focused**: 30 min - 1 hour per section (section review)
|
||||||
|
|
||||||
|
#### Agents Involved
|
||||||
|
|
||||||
|
- **technical-reviewer** (primary)
|
||||||
|
- **code-curator** (supporting for code validation)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Incorporate Review Feedback Workflow
|
||||||
|
|
||||||
|
**ID**: `incorporate-review-feedback-workflow`
|
||||||
|
**Type**: revision
|
||||||
|
|
||||||
|
#### Purpose
|
||||||
|
|
||||||
|
Systematically incorporates feedback from technical reviewers, beta readers, or publishers. Triages feedback, prioritizes changes, implements revisions, and validates corrections.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Received feedback from technical review
|
||||||
|
- Beta reader feedback needs incorporation
|
||||||
|
- Publisher requests revisions
|
||||||
|
- Systematically addressing review comments
|
||||||
|
|
||||||
|
#### Estimated Time
|
||||||
|
|
||||||
|
- Varies based on feedback volume
|
||||||
|
- **Typical**: 4-12 hours per chapter depending on revision scope
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Publishing Workflows
|
||||||
|
|
||||||
|
### PacktPub Submission Workflow
|
||||||
|
|
||||||
|
**ID**: `packtpub-submission-workflow`
|
||||||
|
**Type**: publisher-submission
|
||||||
|
|
||||||
|
#### Purpose
|
||||||
|
|
||||||
|
Prepares and formats manuscript for PacktPub submission. Applies PacktPub-specific formatting, style guidelines, and submission requirements.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Submitting book to PacktPub
|
||||||
|
- Need PacktPub-specific formatting
|
||||||
|
- Preparing chapter deliverables for PacktPub
|
||||||
|
|
||||||
|
#### Agents Involved
|
||||||
|
|
||||||
|
1. **book-publisher** - Applies PacktPub formatting
|
||||||
|
2. **technical-editor** - Verifies PacktPub style compliance
|
||||||
|
3. **book-publisher** - Packages manuscript for submission
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### O'Reilly Submission Workflow
|
||||||
|
|
||||||
|
**ID**: `oreilly-submission-workflow`
|
||||||
|
**Type**: publisher-submission
|
||||||
|
|
||||||
|
#### Purpose
|
||||||
|
|
||||||
|
Prepares and formats manuscript for O'Reilly Media submission. Applies O'Reilly-specific formatting (AsciiDoc, Chicago style), Atlas platform requirements, and submission guidelines.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Submitting book to O'Reilly Media
|
||||||
|
- Need AsciiDoc conversion
|
||||||
|
- Preparing for Atlas platform
|
||||||
|
|
||||||
|
#### Agents Involved
|
||||||
|
|
||||||
|
1. **book-publisher** - Converts to AsciiDoc, applies Chicago style
|
||||||
|
2. **technical-editor** - Verifies O'Reilly format compliance
|
||||||
|
3. **book-publisher** - Packages for Atlas submission
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Manning MEAP Workflow
|
||||||
|
|
||||||
|
**ID**: `manning-meap-workflow`
|
||||||
|
**Type**: publisher-submission
|
||||||
|
|
||||||
|
#### Purpose
|
||||||
|
|
||||||
|
Prepares chapters for Manning Early Access Program (MEAP). Formats chapters for incremental release to early access readers.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Submitting chapters to Manning MEAP
|
||||||
|
- Incremental chapter releases
|
||||||
|
- Need Manning-specific formatting
|
||||||
|
|
||||||
|
#### Agents Involved
|
||||||
|
|
||||||
|
1. **book-publisher** - Applies Manning MEAP formatting
|
||||||
|
2. **technical-editor** - Verifies Manning style
|
||||||
|
3. **book-publisher** - Prepares chapter for MEAP release
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Self-Publishing Workflow
|
||||||
|
|
||||||
|
**ID**: `self-publishing-workflow`
|
||||||
|
**Type**: self-publishing
|
||||||
|
|
||||||
|
#### Purpose
|
||||||
|
|
||||||
|
Prepares manuscript for self-publishing platforms (Leanpub, Gumroad, Amazon KDP, etc.). Handles formatting, cover preparation, metadata, and platform-specific requirements.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Self-publishing book
|
||||||
|
- Need platform-specific formatting (Leanpub Markdown, KDP DOCX, etc.)
|
||||||
|
- Preparing for multiple self-publishing platforms
|
||||||
|
|
||||||
|
#### Agents Involved
|
||||||
|
|
||||||
|
1. **book-publisher** - Formats for target platform
|
||||||
|
2. **technical-editor** - Final quality check
|
||||||
|
3. **book-publisher** - Prepares supplementary materials (cover, metadata)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Brownfield Workflows
|
||||||
|
|
||||||
|
### Book Edition Update Workflow
|
||||||
|
|
||||||
|
**ID**: `book-edition-update-workflow`
|
||||||
|
**Type**: brownfield-revision
|
||||||
|
|
||||||
|
#### Purpose
|
||||||
|
|
||||||
|
Updates existing book for 2nd/3rd edition. Handles technology version migration, content updates, and consistency maintenance with existing style.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Planning 2nd or 3rd edition of existing book
|
||||||
|
- Technology version has changed (e.g., Python 3.10 → 3.12)
|
||||||
|
- Need to update outdated content
|
||||||
|
- Want to maintain consistency with existing book style
|
||||||
|
|
||||||
|
#### Estimated Time
|
||||||
|
|
||||||
|
- Varies significantly based on scope of changes
|
||||||
|
- **Analysis**: 8-16 hours
|
||||||
|
- **Planning**: 6-12 hours
|
||||||
|
- **Implementation**: Depends on changes (can be substantial)
|
||||||
|
|
||||||
|
#### Agents Involved
|
||||||
|
|
||||||
|
1. **book-analyst** - Analyzes existing book, extracts patterns
|
||||||
|
2. **book-analyst** - Assesses version impact
|
||||||
|
3. **version-manager** - Tests code on new versions (if applicable)
|
||||||
|
4. **book-analyst** - Plans surgical revisions
|
||||||
|
5. Various agents - Implements revisions based on plan
|
||||||
|
6. **technical-reviewer** - Validates updates
|
||||||
|
7. **technical-editor** - Ensures consistency with existing style
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Add Chapter to Existing Book Workflow
|
||||||
|
|
||||||
|
**ID**: `add-chapter-to-existing-book-workflow`
|
||||||
|
**Type**: brownfield-addition
|
||||||
|
|
||||||
|
#### Purpose
|
||||||
|
|
||||||
|
Adds new chapter to existing published book. Ensures new chapter matches existing voice, tone, code style, and pedagogical approach.
|
||||||
|
|
||||||
|
#### When to Use
|
||||||
|
|
||||||
|
- Adding new chapter to existing book
|
||||||
|
- Expanding book with additional content
|
||||||
|
- Need consistency with existing chapters
|
||||||
|
- Want new chapter to feel integrated, not appended
|
||||||
|
|
||||||
|
#### Agents Involved
|
||||||
|
|
||||||
|
1. **book-analyst** - Extracts style patterns from existing chapters
|
||||||
|
2. **instructional-designer** - Plans new chapter to fit learning progression
|
||||||
|
3. Standard chapter development agents - Creates chapter following extracted patterns
|
||||||
|
4. **technical-editor** - Verifies consistency with existing book style
|
||||||
|
5. **book-publisher** - Integrates new chapter into book structure
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Workflow Comparison Table
|
||||||
|
|
||||||
|
| Workflow | Category | Time Estimate | Primary Agents | When to Use |
|
||||||
|
|----------|----------|---------------|----------------|-------------|
|
||||||
|
| Book Planning | Planning | 20-33 hrs | book-publisher, instructional-designer, technical-editor | New book concept to approved outline |
|
||||||
|
| Chapter Development (Section) | Development | 54-123 hrs | tutorial-architect, code-curator, technical-reviewer, technical-editor | Large chapters (15+ pages), incremental development |
|
||||||
|
| Chapter Development (Traditional) | Development | 28-51 hrs | tutorial-architect, code-curator, technical-reviewer, technical-editor | Short chapters (<12 pages), full-chapter writing |
|
||||||
|
| Section Planning | Development | 6-11 hrs | tutorial-architect, instructional-designer | Breaking chapter into sections |
|
||||||
|
| Section Development | Development | 5.5-10.5 hrs | code-curator, tutorial-architect, technical-reviewer | Developing one section |
|
||||||
|
| Chapter Assembly | Development | 13-24 hrs | tutorial-architect, instructional-designer, technical-reviewer, technical-editor | Merging sections into chapter |
|
||||||
|
| Tutorial Creation | Development | 14-28 hrs | instructional-designer, tutorial-architect, code-curator | Standalone tutorials |
|
||||||
|
| Code Example | Development | 4-10 hrs | code-curator | Individual code examples |
|
||||||
|
| Technical Review | Review | 3-5 hrs | technical-reviewer | Validating technical accuracy |
|
||||||
|
| Incorporate Feedback | Review | 4-12 hrs | tutorial-architect, technical-reviewer | Addressing review comments |
|
||||||
|
| PacktPub Submission | Publishing | Varies | book-publisher, technical-editor | PacktPub formatting |
|
||||||
|
| O'Reilly Submission | Publishing | Varies | book-publisher, technical-editor | O'Reilly/AsciiDoc formatting |
|
||||||
|
| Manning MEAP | Publishing | Varies | book-publisher, technical-editor | Manning early access |
|
||||||
|
| Self-Publishing | Publishing | Varies | book-publisher, technical-editor | Self-pub platforms |
|
||||||
|
| Edition Update | Brownfield | Varies | book-analyst, version-manager | 2nd/3rd editions |
|
||||||
|
| Add Chapter | Brownfield | Varies | book-analyst, standard agents | Adding to existing book |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Workflow Selection Decision Tree
|
||||||
|
|
||||||
|
**I want to...**
|
||||||
|
|
||||||
|
### Start a new book
|
||||||
|
→ Use **Book Planning Workflow** (20-33 hrs) to create approved outline
|
||||||
|
→ Then proceed to chapter development
|
||||||
|
|
||||||
|
### Write a chapter
|
||||||
|
→ **Is it 15+ pages?** → Use **Chapter Development (Section-Driven)** for incremental progress
|
||||||
|
→ **Is it <12 pages?** → Use **Chapter Development (Traditional)** for faster completion
|
||||||
|
→ **Section-driven flow**: Section Planning → Section Development (×N) → Chapter Assembly
|
||||||
|
|
||||||
|
### Create a tutorial
|
||||||
|
→ Use **Tutorial Creation Workflow** (14-28 hrs) for standalone tutorial
|
||||||
|
→ OR embed tutorial in chapter using Tutorial Architect
|
||||||
|
|
||||||
|
### Develop code examples
|
||||||
|
→ Use **Code Example Workflow** (4-10 hrs per example) for tested, secure code
|
||||||
|
|
||||||
|
### Review content
|
||||||
|
→ Use **Technical Review Workflow** for accuracy validation
|
||||||
|
→ Use **Incorporate Feedback Workflow** to systematically address comments
|
||||||
|
|
||||||
|
### Prepare for publication
|
||||||
|
→ **PacktPub?** → Use **PacktPub Submission Workflow**
|
||||||
|
→ **O'Reilly?** → Use **O'Reilly Submission Workflow**
|
||||||
|
→ **Manning MEAP?** → Use **Manning MEAP Workflow**
|
||||||
|
→ **Self-publishing?** → Use **Self-Publishing Workflow**
|
||||||
|
|
||||||
|
### Update existing book
|
||||||
|
→ **2nd/3rd edition?** → Use **Book Edition Update Workflow**
|
||||||
|
→ **Add new chapter?** → Use **Add Chapter to Existing Book Workflow**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Common Workflow Sequences
|
||||||
|
|
||||||
|
### Greenfield Book (New Book, Section-Driven)
|
||||||
|
|
||||||
|
1. **Book Planning Workflow** (20-33 hrs) → Approved outline
|
||||||
|
2. For each chapter:
|
||||||
|
- **Section Planning Workflow** (6-11 hrs) → Section list
|
||||||
|
- **Section Development Workflow** (×6-8 sections, parallel) → Completed sections
|
||||||
|
- **Chapter Assembly Workflow** (13-24 hrs) → Final chapter
|
||||||
|
3. **Technical Review Workflow** (per chapter or book)
|
||||||
|
4. **Publisher Submission Workflow** → Formatted manuscript
|
||||||
|
|
||||||
|
**Total per chapter**: ~73-158 hrs (section-driven)
|
||||||
|
|
||||||
|
### Greenfield Book (New Book, Traditional)
|
||||||
|
|
||||||
|
1. **Book Planning Workflow** (20-33 hrs) → Approved outline
|
||||||
|
2. For each chapter:
|
||||||
|
- **Chapter Development (Traditional)** (28-51 hrs) → Final chapter
|
||||||
|
3. **Technical Review Workflow** (per chapter)
|
||||||
|
4. **Publisher Submission Workflow** → Formatted manuscript
|
||||||
|
|
||||||
|
**Total per chapter**: ~28-51 hrs (traditional)
|
||||||
|
|
||||||
|
### Brownfield Book (2nd Edition Update)
|
||||||
|
|
||||||
|
1. **Book Edition Update Workflow (Analysis)** (8-16 hrs) → Patterns extracted, impact assessed
|
||||||
|
2. **Book Edition Update Workflow (Planning)** (6-12 hrs) → Revision plan
|
||||||
|
3. For affected chapters:
|
||||||
|
- **Incorporate Feedback Workflow** OR **Chapter Development** (depending on scope)
|
||||||
|
- **Technical Review Workflow** → Validate updates
|
||||||
|
4. **Publisher Submission Workflow** → Updated manuscript
|
||||||
|
|
||||||
|
### Tutorial-Focused Book
|
||||||
|
|
||||||
|
1. **Book Planning Workflow** → Outline
|
||||||
|
2. For each chapter:
|
||||||
|
- **Tutorial Creation Workflow** (×multiple tutorials per chapter)
|
||||||
|
- **Chapter Assembly** → Integrate tutorials into chapter
|
||||||
|
3. **Technical Review Workflow**
|
||||||
|
4. **Publisher Submission Workflow**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
### Workflow Selection
|
||||||
|
|
||||||
|
- **Use section-driven** for chapters 15+ pages, parallel development, incremental progress tracking
|
||||||
|
- **Use traditional** for short chapters, solo authors, simple reference content
|
||||||
|
- **Use brownfield workflows** when updating existing content (maintain consistency)
|
||||||
|
- **Start with planning** - never skip book planning workflow for new books
|
||||||
|
|
||||||
|
### Time Management
|
||||||
|
|
||||||
|
- Section-driven has higher total time but enables parallel work
|
||||||
|
- Traditional is faster for solo authors on short chapters
|
||||||
|
- Time estimates include quality gates - don't skip them
|
||||||
|
- Buffer time for revisions (feedback always reveals issues)
|
||||||
|
|
||||||
|
### Quality Gates
|
||||||
|
|
||||||
|
- Every workflow has quality gates - they prevent rework
|
||||||
|
- Address critical issues before proceeding (cheaper to fix early)
|
||||||
|
- Run checklists at specified points (they catch common errors)
|
||||||
|
- Technical review before editorial polish (preserve accuracy)
|
||||||
|
|
||||||
|
### Agent Coordination
|
||||||
|
|
||||||
|
- Follow workflow sequence - agents depend on prior outputs
|
||||||
|
- Save outputs to specified locations (other agents need them)
|
||||||
|
- Use handoff prompts to communicate context between agents
|
||||||
|
- Parallel development possible in section-driven (check dependencies)
|
||||||
|
|
||||||
|
### Iteration
|
||||||
|
|
||||||
|
- Workflows are iterative - expect revision cycles
|
||||||
|
- Section review catches issues early (before full chapter assembly)
|
||||||
|
- Beta readers provide valuable feedback - use incorporate-feedback workflow
|
||||||
|
- Publishers may request changes - brownfield workflows handle this
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Conclusion
|
||||||
|
|
||||||
|
The BMad Technical Writing Expansion Pack's **15 specialized workflows** orchestrate the complete book authoring lifecycle. By understanding each workflow's purpose, inputs, outputs, and time estimates, you can:
|
||||||
|
|
||||||
|
- **Plan effectively** using structured workflows
|
||||||
|
- **Choose the right approach** (section-driven vs traditional)
|
||||||
|
- **Track progress** with clear milestones
|
||||||
|
- **Maintain quality** through defined quality gates
|
||||||
|
- **Coordinate agents** in optimal sequences
|
||||||
|
- **Handle revisions** systematically
|
||||||
|
|
||||||
|
**Key Innovation**: The **section-driven approach** (v2.0) brings story-driven iterative development to technical book writing, enabling incremental progress, parallel development, and earlier feedback.
|
||||||
|
|
||||||
|
**Total workflow count**: 15
|
||||||
|
**Word count**: ~2,850 words
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Related Documentation**:
|
||||||
|
- [Agent Reference Guide](agent-reference.md) - Detailed agent capabilities
|
||||||
|
- [Template Gallery](template-gallery.md) - Templates used in workflows
|
||||||
|
- [Task Reference](task-reference.md) - Tasks executed by workflows
|
||||||
|
- [User Guide](user-guide.md) - Conceptual overview
|
||||||
|
- [Process Flows](process-flows.md) - Visual Mermaid diagrams for all workflows
|
||||||
Loading…
Reference in New Issue