196 lines
11 KiB
YAML
196 lines
11 KiB
YAML
workflow:
|
||
id: chapter-development-workflow
|
||
name: Write and Refine Chapter
|
||
description: Complete chapter creation workflow from outline to publisher-ready manuscript. v2.0 - Orchestrates section-driven development (section-planning → section-development → chapter-assembly). Can also be used for traditional full-chapter writing. Emphasizes learning objectives, hands-on tutorials, tested code examples, and professional quality standards.
|
||
type: chapter-writing
|
||
version: 2.0
|
||
project_types:
|
||
- technical-book
|
||
- tutorial-series
|
||
- training-materials
|
||
- technical-documentation
|
||
sequence:
|
||
- agent: tutorial-architect
|
||
creates: chapter-outline.md
|
||
requires: book-outline.md
|
||
notes: "Create detailed chapter outline using *create-chapter-outline command. Define learning objectives, prerequisites, main sections, exercises, and code examples needed. SAVE OUTPUT: Copy final chapter-outline.md to docs/outlines/chapter-{{chapter_number}}-outline.md"
|
||
|
||
- agent: tutorial-architect
|
||
creates: section-list.md
|
||
orchestrates: section-planning-workflow
|
||
requires: chapter-outline.md
|
||
notes: "SECTION-DRIVEN APPROACH: Break chapter into 5-8 deliverable sections using section-planning-workflow. Each section 2-5 pages with clear acceptance criteria. Tutorial Architect and Instructional Designer identify section boundaries, create section plans, and validate learning flow. SAVE OUTPUT: docs/sections/chapter-{{chapter_number}}-section-list.md with all section plans. ALTERNATIVE: Skip this step for traditional full-chapter writing approach."
|
||
|
||
- agent: tutorial-architect
|
||
creates: completed-sections[]
|
||
orchestrates: section-development-workflow
|
||
requires: section-list.md
|
||
notes: "SECTION-DRIVEN APPROACH: For each section in section-list, execute section-development-workflow (Code Curator develops code → Tutorial Architect writes section → Technical Reviewer reviews → Tutorial Architect finalizes). Sections can be developed in parallel if dependencies allow. Mark each section DONE when acceptance criteria met. SAVE OUTPUT: docs/sections/chapter-{{chapter_number}}/section-{{n}}-final.md for each section. ALTERNATIVE: Skip and use traditional drafting if not using section approach."
|
||
|
||
- agent: tutorial-architect
|
||
creates: chapter-integrated.md
|
||
orchestrates: chapter-assembly-workflow
|
||
requires: completed-sections[]
|
||
notes: "SECTION-DRIVEN APPROACH: Execute chapter-assembly-workflow to merge all completed sections. Tutorial Architect merges and improves transitions → Instructional Designer validates learning flow → Technical Reviewer performs full chapter review → Tutorial Architect revises → Technical Editor copy edits → Tutorial Architect finalizes. SAVE OUTPUT: docs/chapters/chapter-{{chapter_number}}-final.md. ALTERNATIVE: For traditional approach, use original sequence (code-curator develops all code → tutorial-architect writes full draft → technical-reviewer reviews → revise → copy-edit → finalize)."
|
||
|
||
- agent: tutorial-architect
|
||
validates: chapter-final.md
|
||
requires: chapter-integrated.md
|
||
notes: "FINAL VALIDATION (both approaches): Run chapter-completeness-checklist. Verify all learning objectives addressed, code tested, quality gates passed. Mark chapter status as 'Ready for Publication'. This step ensures quality regardless of section-driven or traditional approach used."
|
||
|
||
flow_diagram: |
|
||
```mermaid
|
||
graph TD
|
||
A[Start: New Chapter] --> B[tutorial-architect: Create Outline]
|
||
B --> C{Section-Driven or Traditional?}
|
||
|
||
C -->|Section-Driven v2.0| D[Plan Sections: section-planning-workflow]
|
||
D --> E[Develop Sections: section-development-workflow]
|
||
E --> F{All Sections DONE?}
|
||
F -->|No| E
|
||
F -->|Yes| G[Assemble Chapter: chapter-assembly-workflow]
|
||
G --> H[Final Validation]
|
||
H --> I[Chapter Ready for Publication]
|
||
|
||
C -->|Traditional| J[code-curator: Develop All Code]
|
||
J --> K[tutorial-architect: Write Full Draft]
|
||
K --> L[technical-reviewer: Review Chapter]
|
||
L --> M{Issues?}
|
||
M -->|Yes| N[Revise]
|
||
N --> L
|
||
M -->|No| O[technical-editor: Copy Edit]
|
||
O --> H
|
||
|
||
D -.-> D1[Break into 5-8 sections]
|
||
E -.-> E1[Parallel development possible]
|
||
G -.-> G1[Merge + Transitions + Review]
|
||
|
||
style I fill:#90EE90
|
||
style B fill:#FFE4B5
|
||
style D fill:#FFE4B5
|
||
style E fill:#FFE4B5
|
||
style G fill:#ADD8E6
|
||
style H fill:#F0E68C
|
||
style J fill:#FFE4B5
|
||
style K fill:#FFE4B5
|
||
```
|
||
|
||
decision_guidance:
|
||
when_to_use_section_driven:
|
||
- Chapters 15+ pages (too large for single sitting)
|
||
- Want incremental progress tracking ("5 of 8 sections complete")
|
||
- Need parallel development (multiple sections in progress)
|
||
- Want to review work-in-progress before full chapter done
|
||
- Prefer story-driven iterative approach (BMad analog)
|
||
|
||
when_to_use_traditional:
|
||
- Short chapters (<10-12 pages)
|
||
- Simple reference sections
|
||
- Author prefers writing full chapter at once
|
||
- Chapter already partially written
|
||
|
||
general_when_to_use:
|
||
- Writing technical book chapters with code examples
|
||
- Creating tutorial-based training materials
|
||
- Developing programming books or guides
|
||
- Need for technical accuracy and professional polish
|
||
- Multiple review stages required
|
||
- Publisher quality standards must be met
|
||
|
||
when_not_to_use:
|
||
- Simple blog posts or articles (use simplified workflow)
|
||
- Reference documentation only (no tutorials)
|
||
- Quick drafts without review requirements
|
||
|
||
quality_gates:
|
||
outline_complete:
|
||
- Learning objectives defined (3-5)
|
||
- Prerequisites clearly stated
|
||
- All code examples identified
|
||
- Exercise plan created
|
||
- Checklist: prerequisite-clarity-checklist.md
|
||
|
||
draft_complete:
|
||
- All sections from outline present
|
||
- Code examples inline and explained
|
||
- Exercises included with hints
|
||
- Learning objectives addressed
|
||
- Checklist: chapter-completeness-checklist.md
|
||
|
||
technical_review_passed:
|
||
- No critical technical errors
|
||
- All code tested and working
|
||
- Security best practices followed
|
||
- No outdated information
|
||
- Checklists: technical-accuracy, security-best-practices, performance-considerations
|
||
|
||
editorial_complete:
|
||
- Grammar and spelling clean
|
||
- Terminology consistent
|
||
- Publisher style followed
|
||
- Accessibility requirements met
|
||
- Checklists: accessibility-checklist, publisher-specific checklist
|
||
|
||
handoff_prompts:
|
||
section_driven_flow:
|
||
outline_to_planning: "Chapter outline complete with {{objective_count}} learning objectives and {{code_count}} code examples. Breaking into sections using section-planning-workflow."
|
||
planning_to_development: "Section planning complete. {{section_count}} sections defined. Each section 2-5 pages with clear acceptance criteria. Begin section-development-workflow for each section."
|
||
development_to_assembly: "All {{section_count}} sections DONE. Total ~{{page_count}} pages of content complete. Ready for chapter-assembly-workflow to merge and polish."
|
||
assembly_to_final: "Chapter assembly complete. All sections integrated with improved transitions. Full technical review and copy editing done. Final validation in progress."
|
||
|
||
traditional_flow:
|
||
architect_to_curator: "Chapter outline complete with {{code_count}} code examples identified. Save outline to docs/outlines/, then develop and test all code examples."
|
||
curator_to_architect: "All code examples developed and tested in chapter-{{chapter_number}}/ folder. Tests passing. Ready for chapter draft writing."
|
||
architect_to_reviewer: "Chapter draft complete at docs/chapters/chapter-{{chapter_number}}-draft.md. All {{objective_count}} learning objectives addressed. Ready for technical review."
|
||
reviewer_to_architect: "Technical review complete. Found {{critical_count}} critical, {{major_count}} major, and {{minor_count}} minor issues. Review report at reviews/technical-review-chapter-{{chapter_number}}.md. Please address and revise."
|
||
revised_to_editor: "Technical review issues addressed. Revised chapter ready for copy editing."
|
||
|
||
both_approaches:
|
||
editor_to_architect: "Copy editing complete. Made improvements to clarity, consistency, and style. Change summary attached. Please review and approve."
|
||
architect_final: "Editorial changes approved. Chapter finalized at docs/chapters/chapter-{{chapter_number}}-final.md. Status: Ready for Publication."
|
||
|
||
time_estimates:
|
||
section_driven_approach:
|
||
create_outline: "2-4 hours"
|
||
plan_sections: "6-11 hours (section-planning-workflow)"
|
||
develop_sections: "33-84 hours (5.5-10.5 hrs per section × 6-8 sections, can be parallel)"
|
||
assemble_chapter: "13-24 hours (chapter-assembly-workflow)"
|
||
total_time: "54-123 hours per chapter (significant parallel development possible)"
|
||
|
||
traditional_approach:
|
||
create_outline: "2-4 hours"
|
||
develop_code: "4-8 hours (depending on complexity)"
|
||
write_draft: "12-20 hours (15-30 page chapter)"
|
||
technical_review: "3-5 hours"
|
||
revision: "4-8 hours"
|
||
copy_edit: "2-4 hours"
|
||
finalization: "1-2 hours"
|
||
total_time: "28-51 hours per chapter (sequential, no parallelization)"
|
||
|
||
comparison_notes: "Section-driven has higher total time but allows parallel work and incremental progress. Traditional is faster for solo authors on short chapters."
|
||
|
||
best_practices:
|
||
general:
|
||
- Start with strong learning objectives - they guide everything
|
||
- Test ALL code before including in chapter
|
||
- Get technical review before editorial polish
|
||
- Address critical issues before moving forward
|
||
- Maintain author voice during editing
|
||
- Keep reader learning experience as top priority
|
||
|
||
section_driven_specific:
|
||
- Choose section-driven for chapters 15+ pages
|
||
- Plan all sections before developing any (see dependencies)
|
||
- Develop sections that have no dependencies in parallel
|
||
- Mark sections DONE only when acceptance criteria met
|
||
- Track progress: "Chapter 3: 5 of 8 sections complete"
|
||
- Review sections incrementally (catch issues early)
|
||
- Use section-driven for story-like iterative workflow
|
||
|
||
traditional_specific:
|
||
- Choose traditional for short chapters (<12 pages)
|
||
- Good for solo authors who prefer full chapter flow
|
||
- Faster for simple reference chapters
|
||
- Use tutorial-section-tmpl for hands-on sections
|
||
- Progressive difficulty in exercises (basic to advanced)
|