Spec: OpenMontage Agent-Only Bundle (Openmontage-PC)

[hlvu002-max]

Problem Statement

Users running OpenMontage on a lightweight secondary device (Openmontage-PC) for AI Agent operations (script generation, scene planning, prompt building, and manual_colab_handoff.json generation) currently face missing dependencies and lost context. When copying only partial agent files, key root routing documents (AGENT_CONTRACT.md, AGENT_GUIDE.md, AGENT_GUIDE.fast.md, CLAUDE.md, AGENTS.md), Cursor/Cata rules (.cursor/rules/, .cata/rules/), and skill directories (.agents/skills/, .claude/skills/, .cursor/skills/) were omitted. This causes LLM agents (Cursor, Claude Code, OpenCode/Cata) to lose system rules, fail venv verification, misconfigure provider priority, or fall back to forbidden ad-hoc production scripts.

Solution

Define and implement a standalone "OpenMontage Agent-Only Bundle" manifest and validation tool (scripts/export_agent_bundle.py / scripts/verify_agent_bundle.py) that exports or verifies a clean, self-contained workspace package for Openmontage-PC. This bundle includes all root routing documentation, workspace rules, agent skills, core pipeline libraries, tool registries, pipeline definitions, and script entrypoints required for full pipeline generation up to Colab handoff, while excluding heavy rendering assets and local FFmpeg media stores.

User Stories

1. As an AI Agent operating on Openmontage-PC, I want access to AGENT_CONTRACT.md, AGENT_GUIDE.fast.md, AGENTS.md, and CLAUDE.md at the workspace root, so that I can immediately follow the mandatory routing and HARD rules without falling back to ad-hoc scripts.
2. As a video creator, I want an automated export script (python scripts/export_agent_bundle.py --output D:/Openmontage-PC) that copies all required agent routers, rules, skills, core modules, and config files to my secondary PC, so that I can set up an agent node in 1 click without manually tracking missing files.
3. As a video creator, I want a verification tool (python scripts/verify_agent_bundle.py) that audits a target workspace directory for all mandatory agent routing docs, rules, skills, and python dependencies, so that I can verify my Openmontage-PC instance is 100% compliant before launching agent jobs.
4. As an AI Agent on Openmontage-PC, I want access to all workspace rules in .cursor/rules/ and .cata/rules/ (e.g., openmontage-venv.mdc, openmontage-provider-priority-strict.mdc, openmontage-fast-video.mdc), so that I am strictly constrained to run inside the .venv interpreter and copy config/provider_priority.yaml values verbatim.
5. As an AI Agent on Openmontage-PC, I want complete skill directories (.agents/skills/, .claude/skills/, .cursor/skills/), so that I can execute specialized workflows like /grill-with-docs, /domain-modeling, /to-spec, and fast-director without missing file errors.
6. As a developer deploying Openmontage-PC, I want heavy local rendering assets (assets/shared/stock/, renders/, .scratch/) excluded from the agent bundle, so that the package remains lightweight (< 50MB) and fast to transfer across machines.
7. As an AI Agent on Openmontage-PC, I want core Python modules (lib/, tools/, pipeline_defs/, scripts/ship_3d_explainer.py) present, so that I can generate script configs, calculate scene beats, resolve TTS selectors, and export manual_colab_handoff.json successfully.
8. As a developer setting up Openmontage-PC, I want clear documentation on recreating the .venv virtual environment via py -3.11 -m venv .venv and pip install -r requirements-dev.txt, so that Python package dependencies are correctly isolated on the target PC.
9. As an AI Agent running ship_3d_explainer.py on Openmontage-PC with full_pipeline: true, I want the ship script to produce artifacts/manual_colab_handoff.json cleanly without attempting local heavy rendering or requiring local GPU assets.

Implementation Decisions

• Bundle Manifest Definition: Establish a canonical manifest data structure listing required root documentation (AGENT_CONTRACT.md, AGENT_GUIDE.md, AGENT_GUIDE.fast.md, CLAUDE.md, AGENTS.md), rule directories (.cursor/rules/*.mdc, .cata/rules/*.mdc), skill directories (.agents/skills/, .claude/skills/, .cursor/skills/), core Python code (lib/, tools/, pipeline_defs/, config/provider_priority.yaml), and entry scripts (scripts/ship_3d_explainer.py, scripts/gen_omnivoice_tts.py).
• Export Script (scripts/export_agent_bundle.py): Implement a CLI tool using Python's shutil and pathlib that reads the manifest, copies all listed files/folders to a specified target directory, creates required empty directories (projects/, renders/), and generates a README_AGENT_PC.md with setup instructions for the target machine.
• Verification Script (scripts/verify_agent_bundle.py): Implement an audit script that checks a directory for the presence and non-emptiness of all manifest items, returning exit code 0 if fully compliant or listing missing files/folders and returning exit code 1 if incomplete.
• Rule & Skill Mirroring: Ensure .cursor/rules/, .cata/rules/, .agents/skills/, .claude/skills/, and .cursor/skills/ are copied recursively without filtering out any .md or .yaml files.
• Venv Isolation Contract: Enforce that the target machine must create its own virtual environment using .venv/ and requirements-dev.txt, forbidding direct copy of binary .venv folders between host architectures.

Testing Decisions

• External Behavior Tests: Test the exporter and verification scripts using end-to-end dry run tests in a temporary directory (pytest in tests/scripts/test_agent_bundle.py).
• Seam: The seam for testing is the CLI interface of export_agent_bundle.py and verify_agent_bundle.py against a temporary target path (tmp_path).
• Verification Criteria:
  1. export_agent_bundle.py --target <tmp_path> executes with exit code 0.
  2. verify_agent_bundle.py --path <tmp_path> executes with exit code 0 on the exported directory.
  3. Deleting any critical file (e.g. <tmp_path>/AGENT_CONTRACT.md or <tmp_path>/.cursor/rules/openmontage.mdc) causes verify_agent_bundle.py to fail with exit code 1 and explicitly name the missing resource.

Out of Scope

• Synchronizing heavy local stock assets (assets/shared/stock/) or pre-rendered video clips.
• Automatic installation of system-level Python or FFmpeg on the target PC.
• Modifying config/provider_priority.yaml or altering the full_pipeline: true remote handoff logic.

Further Notes

• The resulting agent-only bundle allows Openmontage-PC to serve as a high-speed, lightweight orchestration node for AI agents.
• All heavy rendering remains offloaded to Google Colab via colab_process_explainer.py as specified in AGENT_CONTRACT.md.

[AbarnaaSree]

Hi, I’d like to work on issue #477 (OpenMontage Agent-Only Bundle). I’ve gone through the requirements and can implement the export script, verification script, and the corresponding tests. Could you please assign this issue to me?