AGENTS
Agent definitions for PPTX automation pipeline.
Design Principles
| Principle | Description |
|---|
| SSOT | Each rule defined in one place only; others reference it |
| Agent vs Script | AI judgment needed → Agent; deterministic → Script |
| IR Separation | Agents communicate via JSON (content.json) loosely coupled |
| Fail Fast | Early error detection; escalate after 3 retries |
| Human in the Loop | User confirmation required for important decisions |
📖 See common.instructions.md for details.
Documentation SSOT Map
| Topic | Source (SSOT) |
|---|
| PLAN Phase Confirmation | instructions/plan-phase.instructions.md |
| Naming & Bullet Rules | instructions/common.instructions.md |
| Quality Guidelines | instructions/quality-guidelines.instructions.md |
| Tools & Workflow | instructions/tools-reference.instructions.md |
| IR Schema | schemas/content.schema.json |
| Error Recovery | instructions/error-recovery.instructions.md |
| Script Dependencies | instructions/script-dependencies.instructions.md |
| Speaker Notes Quality | instructions/quality-guidelines.instructions.md |
| content_with_image | instructions/template-advanced.instructions.md |
Agent List
| Agent | Manifest | Role |
|---|
| Brainstormer | agents/brainstormer.agent.md | Interactive ideation → proposal.json |
| Orchestrator | agents/orchestrator.agent.md | State management, planning, retry control |
| Localizer | agents/localizer.agent.md | Translation only (AI judgment) |
| Summarizer | agents/summarizer.agent.md | Summarization & restructuring (AI judgment) |
| JSON Reviewer | agents/json-reviewer.agent.md | content.json review (translation, structure) |
| PPTX Reviewer | agents/pptx-reviewer.agent.md | PPTX review (visual, notes, CTA quality) |
⚠️ reviewer.agent.md was renamed and split into json-reviewer.agent.md.
Script List
| Script | Purpose | Auto-Fix Features |
|---|
classify_input.py | Input classification | - |
validate_content.py | IR schema validation | - |
validate_pptx.py | PPTX validation | - |
review_pptx.py | PPTX content extraction for review | - |
create_from_template.py | PPTX generation | AutoFit disable, position adjust |
create_clean_template.py | Clean template from source PPTX | Vertical text fix, decoration trim |
diagnose_template.py | Template quality diagnosis | - |
clean_template.py | Template cleaning | Background removal, ref fix |
analyze_template.py | Layout analysis → layouts.json | - |
merge_slides.py | Merge diagram slides into template | - |
insert_diagram_slides.py | Insert diagram slides at position | Scaling, layout selection |
workflow_tracer.py | Trace log output | - |
📖 See script-dependencies.instructions.md for dependencies.
Standard Workflow
Main Flow (★ Always start from Orchestrator)
┌─────────────────────────────────────────┐
│ TRIAGE (Orchestrator decides) │
└──────────────┬──────────────────────────┘
│
┌──────────────────────────────┼──────────────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ A: Needs │ │ B: Input │ │ C: Resume │
│ Brainstorm │ │ Provided │ │ Workflow │
│ → BRAINSTORM │ │ → INIT │ │ → Target Phase │
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
│ │ │
▼ │ │
proposal.json │ │
│ │ │
└──────────────────────────────┴──────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────────────┐
│ INIT → PLAN(confirm) → PREPARE_TEMPLATE → EXTRACT → [SUMMARIZE] │
│ → TRANSLATE → REVIEW(JSON) → BUILD → REVIEW(PPTX) → DONE │
│ │ │ │
│ └────(FAIL → fix, max 3×)─────────────┘ │
│ ↓ │
│ ESCALATE (>3 failures) │
└───────────────────────────────────────────────────────────────────────┘
Phase Details
| Phase | Owner | Description |
|---|
| TRIAGE | Orchestrator | Input detection, workflow branching (★ first) |
| BRAINSTORM | Brainstormer | Interactive → proposal.json (optional) |
| INIT | classify_input.py | Input detection → classification.json |
| PLAN | Orchestrator | Present options, get user approval (★ required) |
| PREPARE_TEMPLATE | create_clean_template | Template diagnosis, cleaning, position fix |
| EXTRACT | Script group | Image extraction + content.json (parallelizable) |
| SUMMARIZE | Summarizer | Slide count reduction only: summarize |
| TRANSLATE | Localizer | content.json → content_ja.json |
| REVIEW(JSON) | JSON Reviewer | content.json quality check → pass/fail |
| BUILD | create_from_template.py | PPTX generation (auto position, AutoFit) |
| REVIEW(PPTX) | PPTX Reviewer | Visual, notes, CTA quality review → pass/fail |
| DONE | Orchestrator | Open PowerPoint (optional) |
| ESCALATE | workflow_tracer.py | Human escalation after 3 failures |
Auto-Fixes in PREPARE_TEMPLATE
| Detection | Fix Action | Related Issue |
|---|
| Off-slide shapes | Remove | #41 Vertical text |
| Left-edge decorations | Remove | #35 Title offset |
| Narrow placeholders | Widen | #39 Title line wrap |
Auto-Fixes in BUILD
| Detection | Fix Action | Related Issue |
|---|
| AutoFit text spacing | Disable | #42 Japanese text spacing |
| Title position (Section) | Fix at 35% | #43 Position issues |
| Subtitle position | Title + 0.15" | #37 Too far apart |
📖 See error-recovery.instructions.md for recovery details.
Common I/O Contract
| Type | Path |
|---|
| User Input | input/ |
| Intermediate | output_manifest/{base}_*.json |
| Images | images/{base}/ |
| Final Output | output_ppt/{base}.pptx |
Base naming convention: {YYYYMMDD}_{keyword}_{purpose}
Method Selection
| Use Case | Recommended Method | Rating |
|---|
| EN PPTX → Japanese | reconstruct + create_from_template | ⭐⭐⭐⭐⭐ |
| With Template | analyze_template + create_from_template | ⭐⭐⭐⭐⭐ |
| From scratch | create_ja_pptx.py | ⭐⭐⭐⭐ |
| Code-heavy content | pptxgenjs | ⭐⭐⭐⭐ |
Operational Rules
- Follow instructions documents within this skill
- Direct editing of templates/PPTX is prohibited
- Run
analyze_template.py when using new templates
Troubleshooting
Common issues and solutions:
- Template load error: Run
diagnose_template.py to diagnose template
- Image overlap: Add
content_with_image mapping to layouts.json
- Text overflow: Detect with
validate_pptx.py, reduce item count
- Translation quality: Auto-checked by JSON Reviewer, escalate after 3 retries