AGENTS.md@powerpoint-automation/references · git:20261004.e1c4ed1 · 2026-10-04 · sha256 478de28faeb22676
AGENTS.md@powerpoint-automation/references git:20261004.e1c4ed1A
Immutable. This exact content never changes and is served at /api/v1/blob/478de28faeb22676.
# 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) |
## 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
Always start from the Orchestrator. Main flow, phase owners, PLAN options, retry policy (max 3, then ESCALATE), and fallback matrix: [agents/orchestrator.agent.md](agents/orchestrator.agent.md).
### 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
See [tools-reference.instructions.md](instructions/tools-reference.instructions.md#method-selection) (SSOT).
---
## 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