Ad Creative Orchestrator

Turn an advertising brief into a traceable, versioned project workspace—with explicit review gates before anything becomes client-visible.

Ad Creative Orchestrator (ADCO) is a local-first CLI and Codex control plane for creative operations. Core project state stays on disk; provider-facing generation, external uploads, and client delivery require explicit approval.

中文简介：ADCO 把广告项目的资料、方案、视觉资产、PPT、审阅与交付状态收进一个可追溯的本地工作区，并在客户可见和发送前强制停下等待人工确认。

Alpha: use version control or backups and keep a human reviewer in the loop for real client work.

Why ADCO

Creative projects rarely fail because a team cannot make another slide. They fail because the latest brief, approved copy, image rights, deck version, and client feedback drift apart.

ADCO gives each project a file-based source of truth:

• Current state: requirements, gaps, decisions, work items, and versions stay readable on disk.
• Versioned deliverables: PPTX files and client packages are immutable and bound to exact-current inputs.
• Review gates: copy, references, assets, layout, editability, and send readiness are checked separately.
• Human handoffs: a browser dashboard and bilingual folders show non-developers what is current and what happens next.
• Safe automation: external uploads, paid actions, destructive overwrites, global installs, and client sends require explicit approval.

Quickstart

ADCO requires Python 3.10 or newer. Install the current release with pipx:

pipx install --force https://github.com/papperrollinggery/ad-creative-orchestrator/releases/download/v0.3.2/ad_creative_orchestrator-0.3.2-py3-none-any.whl
adco --version
adco doctor

Create and inspect a safe demo:

adco quickstart /tmp/adco-demo --no-open
adco open-dashboard /tmp/adco-demo
adco status /tmp/adco-demo
adco next /tmp/adco-demo

Expected first-run checks:

QUICKSTART=PASS
VALIDATION=PASS

The dashboard is generated at:

/tmp/adco-demo/AD-creative/handoff/操作台.html

For source installation, upgrades, Skill installation, and uninstall instructions, see the installation guide.

Start a Real Project

adco init <project_dir>
adco run <project_dir> --material <brief_or_material_folder>
adco open-dashboard <project_dir>
adco status <project_dir>
adco next <project_dir>

adco run registers the source material, extracts requirements and gaps, builds the handoff dashboard, creates a customer-readable text framework, and stops for human confirmation. It does not automatically create or send a presentation.

Every new workspace includes:

project/
├── 00_项目资料_ProjectMaterials/
├── 01_参考资料_References/
├── 02_重要素材_KeyAssets/
├── 03_阶段成果_WorkInProgress/
├── 04_客户审阅_ClientReview/
├── 05_最终交付_FinalDelivery/
└── AD-creative/
    ├── handoff/          # dashboard, project board, questions, next steps
    └── orchestrator/     # requirements, gaps, versions, gates, audit trail

If the project already has an AGENTS.md, ADCO leaves it untouched and writes an AGENTS.merge_suggestion.md for manual review.

How the Workflow Stays Safe

Briefs and feedback
        ↓
Requirements and gaps
        ↓
Client-readable outline ── human hash-bound confirmation
        ↓
References, creative work, and specialist handoffs
        ↓
Immutable PPTX version ── language, asset, layout, and editability checks
        ↓
Exact-current client package ── independent review + send authorization
        ↓
Send-readiness result (ADCO never sends)

The project lifecycle keeps truth, outline approval, creative work, presentation export, package binding, independent review, and feedback as separate states. Passing one state never silently approves the next.

Important boundaries:

• VALIDATION=PASS proves structural integrity and traceability—not creative quality, client approval, asset rights, or permission to send.
• client-pack-gate means a package is ready for independent review—not ready to send.
• client-send-readiness-gate checks that independent review and explicit authorization match the same current package. It never sends files.
• AI-generated images remain internal until visual QA and hash-bound authorization are recorded.
• Files manually placed in 05_最终交付_FinalDelivery/ are protected from automatic move, overwrite, and deletion.

Read the authorization policy for the complete stop conditions.

Core Commands

Command	Purpose
adco quickstart [project_dir]	Create, validate, and open a safe first-run demo.
adco run <project_dir> --material <path>	Register real materials and produce the first project state.
adco status <project_dir>	Show blockers, pending confirmations, and current validation.
adco next <project_dir>	Print the next safe action.
adco open-dashboard <project_dir>	Open the non-developer project dashboard.
adco validate <project_dir>	Validate structure and traceability.
adco support-bundle <project_dir>	Create a local diagnostic bundle; review it before sharing.
adco docs	Locate the packaged README, changelog, and operating guides.
adco check	Run the repository's deterministic checks.

Run adco --help or adco <command> --help for the complete CLI reference. The operating manual explains the full workflow and gate commands.

What ADCO Owns—and What It Does Not

ADCO owns project truth, traceable proposal drafts, artifact versions, review evidence, specialist adoption, presentation/client-package binding, FinalDelivery protection, and send-readiness checks.

ADCO is not a SaaS, image generator, video generator, autonomous creative approver, or delivery bot. Image and film work can come from specialist tools through a versioned exchange contract; ADCO remains the owner of adoption, provenance, and client-facing readiness.

Documentation

Start here	Use it for
Non-developer quickstart	Starting a project without learning the full CLI.
First real project runbook	Running a live project from intake through handoff.
Operating manual	Commands, gates, and lifecycle details.
Adoption patterns	Adding ADCO to an existing workflow.
Real-project acceptance criteria	Deciding whether a project is genuinely ready.
Specialist exchange v1	Integrating external image, film, or craft specialists.
Security policy	Reporting vulnerabilities without exposing client data.
Changelog	User-visible changes by release.
Roadmap	Planned product work.

docs/operating/ is the current operator contract. docs/design/ records design rationale, while docs/reviews/ contains historical evidence and may include old paths or commands.

Development

git clone https://github.com/papperrollinggery/ad-creative-orchestrator.git
cd ad-creative-orchestrator
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
make check

Release candidates must also pass:

make release-check

The public CI runs the release checks on Python 3.10 and 3.12. See the release checklist before publishing a new version.

Current Release

The current public release is v0.3.2. Use the Release tag target to identify the source commit and the published wheel as the installation artifact.

Compared with earlier releases, v0.3.2 makes current materials easier to find, protects final-delivery files from silent replacement, strengthens specialist and review evidence, and packages the operator guides available through adco docs. See the changelog for technical details.

Contributing and Security

Bug reports and focused pull requests are welcome. Use the issue templates and describe the smallest reproducible project state without attaching confidential client materials.

Report vulnerabilities through GitHub private vulnerability reporting. See SECURITY.md for scope and disclosure guidance.

License

MIT