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