AGENTS.md@powerpoint-automation/references · git:20260705.848fd9b · 2026-07-05 · sha256 1241d4a88aad8de9
AGENTS.md@powerpoint-automation/references git:20260705.848fd9bA
Immutable. This exact content is served forever at /api/v1/blob/1241d4a88aad8de9.
# 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](instructions/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` |
| COM Automation Rules | `instructions/com-automation.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](instructions/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](instructions/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