AGENTS.md@powerpoint-automation/references · diff

git:20260705.848fd9b to git:20261004.e1c4ed1

2 added, 57 removed. Audit A to A.

# 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 |

+ 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

- | 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 | ⭐⭐⭐⭐ |

+ 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