153 lines
7.8 KiB
Plaintext
153 lines
7.8 KiB
Plaintext
workflow:
|
|
id: chapter-development-workflow
|
|
name: Write and Refine Chapter
|
|
description: Complete chapter creation workflow from outline to publisher-ready manuscript. Guides technical authors through planning, drafting, code development, technical review, and editorial polish. Emphasizes learning objectives, hands-on tutorials, tested code examples, and professional quality standards.
|
|
type: chapter-writing
|
|
project_types:
|
|
- technical-book
|
|
- tutorial-series
|
|
- training-materials
|
|
- technical-documentation
|
|
sequence:
|
|
- agent: tutorial-architect
|
|
creates: chapter-outline.md
|
|
requires: book-outline.md
|
|
notes: "Create detailed chapter outline using *create-chapter-outline command. Define learning objectives, prerequisites, main sections, exercises, and code examples needed. SAVE OUTPUT: Copy final chapter-outline.md to docs/outlines/chapter-{{chapter_number}}-outline.md"
|
|
|
|
- agent: code-curator
|
|
creates: code-examples/
|
|
requires: chapter-outline.md
|
|
notes: "Develop and test all code examples identified in outline. Use *create-example for each example. Ensure all code runs correctly, follows best practices, and includes proper error handling. SAVE OUTPUT: Commit code to repository in chapter-{{chapter_number}}/ folder with tests."
|
|
|
|
- agent: tutorial-architect
|
|
creates: chapter-draft.md
|
|
requires:
|
|
- chapter-outline.md
|
|
- code-examples/
|
|
notes: "Write complete chapter draft using write-chapter-draft task. Include introduction, main content sections with tutorials, code examples inline, practice exercises, and summary. Ensure all learning objectives addressed. SAVE OUTPUT: Copy final draft to docs/chapters/chapter-{{chapter_number}}-draft.md"
|
|
|
|
- agent: technical-reviewer
|
|
creates: technical-review-report.md
|
|
requires: chapter-draft.md
|
|
notes: "Perform comprehensive technical review using *review-chapter command. Verify technical accuracy, test all code, check security best practices, assess performance. Use technical-accuracy-checklist, security-best-practices-checklist, and performance-considerations-checklist. SAVE OUTPUT: Copy review report to reviews/technical-review-chapter-{{chapter_number}}.md"
|
|
|
|
- agent: tutorial-architect
|
|
updates: chapter-draft.md
|
|
requires: technical-review-report.md
|
|
notes: "Revise chapter based on technical review feedback. Address all Critical issues and Major issues. Update code examples if needed. Test revised code. Mark story status as 'Revision-Technical' during this phase. SAVE OUTPUT: Update chapter-draft.md with revisions."
|
|
|
|
- agent: technical-editor
|
|
updates: chapter-draft.md
|
|
requires: revised-chapter-draft.md
|
|
notes: "Perform professional copy edit using *edit-chapter command. Improve clarity, check consistency, enhance transitions, verify publisher style compliance, review accessibility. Use accessibility-checklist and publisher-specific checklist. SAVE OUTPUT: Return edited chapter with change summary."
|
|
|
|
- agent: tutorial-architect
|
|
finalizes: chapter-final.md
|
|
requires: edited-chapter.md
|
|
notes: "Review and approve editorial changes. Ensure technical accuracy preserved during editing. Create final chapter version. Mark chapter status as 'Ready for Publication'. SAVE OUTPUT: Copy final chapter to docs/chapters/chapter-{{chapter_number}}-final.md"
|
|
|
|
flow_diagram: |
|
|
```mermaid
|
|
graph TD
|
|
A[Start: New Chapter] --> B[tutorial-architect: Create Outline]
|
|
B --> C[code-curator: Develop Code Examples]
|
|
C --> D[tutorial-architect: Write Chapter Draft]
|
|
D --> E[technical-reviewer: Technical Review]
|
|
E --> F{Critical/Major Issues?}
|
|
F -->|Yes| G[tutorial-architect: Revise Chapter]
|
|
F -->|No| H[technical-editor: Copy Edit]
|
|
G --> I[code-curator: Update Code if Needed]
|
|
I --> E
|
|
H --> J[tutorial-architect: Review Edits]
|
|
J --> K{Approve Edits?}
|
|
K -->|Yes| L[Finalize Chapter]
|
|
K -->|No| M[Discuss with Editor]
|
|
M --> H
|
|
L --> N[Chapter Ready for Publication]
|
|
|
|
B -.-> B1[Optional: *create-learning-objectives]
|
|
C -.-> C1[Optional: *test-code]
|
|
E -.-> E1[Optional: *security-audit]
|
|
E -.-> E2[Optional: *verify-accuracy]
|
|
|
|
style N fill:#90EE90
|
|
style B fill:#FFE4B5
|
|
style C fill:#FFE4B5
|
|
style D fill:#FFE4B5
|
|
style E fill:#ADD8E6
|
|
style H fill:#ADD8E6
|
|
style L fill:#F0E68C
|
|
```
|
|
|
|
decision_guidance:
|
|
when_to_use:
|
|
- Writing technical book chapters with code examples
|
|
- Creating tutorial-based training materials
|
|
- Developing programming books or guides
|
|
- Need for technical accuracy and professional polish
|
|
- Multiple review stages required
|
|
- Publisher quality standards must be met
|
|
|
|
when_not_to_use:
|
|
- Simple blog posts or articles (use simplified workflow)
|
|
- Reference documentation only (no tutorials)
|
|
- Quick drafts without review requirements
|
|
|
|
quality_gates:
|
|
outline_complete:
|
|
- Learning objectives defined (3-5)
|
|
- Prerequisites clearly stated
|
|
- All code examples identified
|
|
- Exercise plan created
|
|
- Checklist: prerequisite-clarity-checklist.md
|
|
|
|
draft_complete:
|
|
- All sections from outline present
|
|
- Code examples inline and explained
|
|
- Exercises included with hints
|
|
- Learning objectives addressed
|
|
- Checklist: chapter-completeness-checklist.md
|
|
|
|
technical_review_passed:
|
|
- No critical technical errors
|
|
- All code tested and working
|
|
- Security best practices followed
|
|
- No outdated information
|
|
- Checklists: technical-accuracy, security-best-practices, performance-considerations
|
|
|
|
editorial_complete:
|
|
- Grammar and spelling clean
|
|
- Terminology consistent
|
|
- Publisher style followed
|
|
- Accessibility requirements met
|
|
- Checklists: accessibility-checklist, publisher-specific checklist
|
|
|
|
handoff_prompts:
|
|
architect_to_curator: "Chapter outline complete with {{code_count}} code examples identified. Save outline to docs/outlines/, then develop and test all code examples."
|
|
curator_to_architect: "All code examples developed and tested in chapter-{{chapter_number}}/ folder. Tests passing. Ready for chapter draft writing."
|
|
architect_to_reviewer: "Chapter draft complete at docs/chapters/chapter-{{chapter_number}}-draft.md. All {{objective_count}} learning objectives addressed. Ready for technical review."
|
|
reviewer_to_architect: "Technical review complete. Found {{critical_count}} critical, {{major_count}} major, and {{minor_count}} minor issues. Review report at reviews/technical-review-chapter-{{chapter_number}}.md. Please address and revise."
|
|
revised_to_editor: "Technical review issues addressed. Revised chapter ready for copy editing."
|
|
editor_to_architect: "Copy editing complete. Made improvements to clarity, consistency, and style. Change summary attached. Please review and approve."
|
|
architect_final: "Editorial changes approved. Chapter finalized at docs/chapters/chapter-{{chapter_number}}-final.md. Status: Ready for Publication."
|
|
|
|
time_estimates:
|
|
create_outline: "2-4 hours"
|
|
develop_code: "4-8 hours (depending on complexity)"
|
|
write_draft: "12-20 hours (15-30 page chapter)"
|
|
technical_review: "3-5 hours"
|
|
revision: "4-8 hours"
|
|
copy_edit: "2-4 hours"
|
|
finalization: "1-2 hours"
|
|
total_time: "28-51 hours per chapter"
|
|
|
|
best_practices:
|
|
- Start with strong learning objectives - they guide everything
|
|
- Test ALL code before including in chapter
|
|
- Use tutorial-section-tmpl for hands-on sections
|
|
- Progressive difficulty in exercises (basic to advanced)
|
|
- Get technical review before editorial polish
|
|
- Address critical issues before moving forward
|
|
- Maintain author voice during editing
|
|
- Keep reader learning experience as top priority
|