### Install and start AutoDesign locally

Source: https://github.com/yaxin9luo/autodesign/blob/main/README.md

One-command local launch. Requires Node.js 22+ and ffmpeg/ffprobe. Installs under ~/.local/share/autodesign, keeps state under ~/.autodesign, serves the bundled web/dist, and opens a browser. Existing ~/.designanything state is migrated with a compatibility symlink.

```bash
curl -fsSL https://designanything.ai/install.sh | bash
autodesign start
```

--------------------------------

### Install all four AutoDesign skills on Windows

Source: https://github.com/yaxin9luo/autodesign/blob/main/agent_skills/README.md

Windows example for downloading and installing all four AutoDesign skills. Change $Destination for Codex or DeepSeek Harness. Uses py -3 as the Python launcher.

```powershell
New-Item -ItemType Directory -Force autodesign-skills-v0.2.0 | Out-Null
gh release download agent-skills-v0.2.0 `
  --repo Yaxin9Luo/AutoDesign `
  --dir autodesign-skills-v0.2.0
Set-Location autodesign-skills-v0.2.0

$Destination = "$HOME\.claude\skills"
foreach ($Skill in @("autodesign-poster", "autodesign-ppt", "autodesign-webpage", "autodesign-video")) {
  py -3 -I .\package_agent_skills.py install `
    --archive ".\$Skill-0.2.0.zip" `
    --checksum ".\$Skill-0.2.0.zip.sha256" `
    --destination $Destination
}
```

--------------------------------

### Install AutoDesign with OCR extra

Source: https://github.com/yaxin9luo/autodesign/blob/main/eval/README.md

Installs AutoDesign with the benchmark OCR dependencies. Run this before configuring provider credentials.

```bash
uv sync --extra ocr
```

--------------------------------

### Install a single AutoDesign skill with installer

Source: https://github.com/yaxin9luo/autodesign/blob/main/agent_skills/README.md

Installs a single AutoDesign skill (autodesign-poster) with its matching checksum. Replace autodesign-poster with another skill name and choose the destination for your Coding Agent. The installer verifies SHA-256, validates extracted contents, promotes atomically, and refuses to overwrite an existing Skill.

```bash
python3 -I ./package_agent_skills.py install \
  --archive ./autodesign-poster-0.2.0.zip \
  --checksum ./autodesign-poster-0.2.0.zip.sha256 \
  --destination "$HOME/.agents/skills"
```

--------------------------------

### Install dependencies and render PDF with pdftoppm

Source: https://github.com/yaxin9luo/autodesign/blob/main/skills/common/pdf_render_qa/references/pdf_render_commands.md

Install required Python packages and the poppler utility, then render a PDF to PNG images with pdftoppm. Run these commands when dependencies are missing; report missing dependencies rather than skipping QA.

```bash
uv pip install reportlab pdfplumber pypdf
brew install poppler
pdftoppm -png "$INPUT_PDF" "$OUTPUT_PREFIX"
```

--------------------------------

### Install all four AutoDesign skills with installer loop

Source: https://github.com/yaxin9luo/autodesign/blob/main/agent_skills/README.md

Installs all four AutoDesign skills into the shared Codex and DeepSeek Harness user directory. The installer checks SHA-256, validates the extracted package, promotes it atomically, and refuses to overwrite an existing installation.

```bash
DESTINATION="${DESTINATION:-$HOME/.agents/skills}"

for skill in autodesign-poster autodesign-ppt autodesign-webpage autodesign-video; do
  python3 -I ./package_agent_skills.py install \
    --archive "./${skill}-0.2.0.zip" \
    --checksum "./${skill}-0.2.0.zip.sha256" \
    --destination "$DESTINATION"
done
```

--------------------------------

### Install dependencies from source

Source: https://github.com/yaxin9luo/autodesign/blob/main/README.md

Build from source. Requirements: Python 3.10+, uv, Node.js 22+, npm, and ffmpeg/ffprobe for Video. Configure provider keys in .env or in the Web UI Settings drawer; do not replace an existing .env during an update.

```bash
uv sync
uv run python scripts/install_playwright_browsers.py
cd runtime/video && npm ci --omit=dev
cd ../../web && npm install
```

--------------------------------

### Run smoke evaluation with run_poster_benchmark_main_table.py

Source: https://github.com/yaxin9luo/autodesign/blob/main/eval/README.md

Runs a quick evaluation on a limited number of examples (--limit 2) with a single worker to verify the setup before running the full evaluation.

```bash
uv --cache-dir .uv-cache run --extra ocr \
  python scripts/run_poster_benchmark_main_table.py \
  --paper-root eval/EvaData \
  --systems codex_native \
  --codex-native-root /absolute/path/to/candidates \
  --system-label "codex_native=Your System" \
  --model gemini-3.5-flash \
  --limit 2 \
  --workers 1 \
  --out-dir out/eval/your-system-smoke
```

--------------------------------

### Start frontend dev server

Source: https://github.com/yaxin9luo/autodesign/blob/main/README.md

Start the frontend development server in another terminal. Open localhost:5173 to access the workbench.

```bash
cd web
npm run dev
```

--------------------------------

### Start the interactive CLI with uv

Source: https://github.com/yaxin9luo/autodesign/blob/main/README.md

Starts the interactive CLI for AutoDesign. Use this command to launch the command-line interface.

```bash
uv --cache-dir .uv-cache run python -m autodesign
```

--------------------------------

### Serve local acceptance gallery

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-poster-agent-first-v2.md

Starts a local HTTP server on a free loopback port to serve the acceptance gallery. The port is chosen dynamically using a Python one-liner, and the server serves the acceptance root directory.

```bash
PORT="$(python3 - <<'PY'
import socket
with socket.socket() as listener:
    listener.bind(("127.0.0.1", 0))
    print(listener.getsockname()[1])
PY
)"
python3 -m http.server "$PORT" --bind 127.0.0.1 \
  --directory "$ACCEPTANCE_ROOT"
```

--------------------------------

### Launch backend with uvicorn

Source: https://github.com/yaxin9luo/autodesign/blob/main/README.md

Start the backend server. Run in one terminal; the frontend is started separately. Backend health is available at /api/health.

```bash
uv run uvicorn scripts.web_server:app --reload --port 8000
```

--------------------------------

### Markdown: required README section headings

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-agent-skills-launch.md

Required section headings for the dedicated agent_skills/README.md guide. The guide must include exact gh skill install commands for the four nested package paths and the checksum-verified ZIP installer fallback.

```markdown
## Quick install
## Install by Coding Agent
## First run
## Requirements
## Skills vs. the full AutoDesign Harness
## Roadmap and contributing
## Maintainer verification
```

--------------------------------

### Begin attempt and stage visual

Source: https://github.com/yaxin9luo/autodesign/blob/main/agent_skills/autodesign-webpage/SKILL.md

Starts a new attempt and captures its attempt_id, then stages a visual with the given visual ID. The attempt_id is stored in ATTEMPT_ID for subsequent commands.

```bash
ATTEMPT_ID="$(python3 "$HARNESS" begin --run-dir "$RUN_DIR" | python3 -c 'import json,sys; print(json.load(sys.stdin)["attempt_id"])')"
python3 "$HARNESS" stage-visual --run-dir "$RUN_DIR" --attempt "$ATTEMPT_ID" --visual-id vis-001
```

--------------------------------

### Set DESTINATION for DeepSeek Harness skills

Source: https://github.com/yaxin9luo/autodesign/blob/main/agent_skills/README.md

Sets the destination directory for a DeepSeek Harness-only user installation. Set this in the same shell before running the Quick install loop; the loop preserves a destination you already selected. Use DESTINATION="$HOME/.agents/skills" instead for a shared installation with Codex.

```bash
DESTINATION="$HOME/.dsh/skills"
```

--------------------------------

### Hash-bound review JSON (failure example)

Source: https://github.com/yaxin9luo/autodesign/blob/main/agent_skills/autodesign-webpage/references/review-rubric.md

For a failure, name concrete regions and fixes. The example shows a blocker for mobile results table clipping, a localized repair with region and issue, and verdict 'fail'.

```json
{
  "blockers": ["mobile results table clips its final metric column"],
  "localized_repairs": [
    {"region": "#results table", "issue": "mobile overflow", "repair": "use a labeled native overflow wrapper and keep headers visible"}
  ],
  "verdict": "fail"
}
```

--------------------------------

### Hash-bound review JSON (passing example)

Source: https://github.com/yaxin9luo/autodesign/blob/main/agent_skills/autodesign-webpage/references/review-rubric.md

Copy these binding fields exactly from review-context.json for a passing review. The example shows the required structure with dimension scores, empty blockers, and verdict 'pass'.

```json
{
  "format_version": 1,
  "attempt_id": "<actual attempt_id from begin>",
  "review_context_sha256": "...",
  "artifact_hashes": {},
  "preview_hashes": {"desktop": "...", "mobile": "..."},
  "reviewed_frame_ids": ["desktop", "mobile"],
  "source_manifest_sha256": "...",
  "rubric_sha256": "...",
  "source_map_sha256": "...",
  "reviewer_mode": "fresh_subagent",
  "dimension_scores": {
    "source_fidelity": 4,
    "research_narrative": 4,
    "visual_hierarchy": 4,
    "typography": 4,
    "evidence_use": 4,
    "interaction_utility": 4,
    "accessibility_responsive": 4,
    "anti_slop": 4
  },
  "blockers": [],
  "localized_repairs": [],
  "verdict": "pass",
  "complete": true
}
```

--------------------------------

### Install Poster archive into fresh temp root

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-poster-agent-first-v2.md

Bash commands to install the Poster archive into a fresh temporary host root using the release-local installer, then make the installed tree read-only. Used in Step 3 to verify a read-only installed package.

```bash
INSTALL_ROOT="$(mktemp -d /tmp/autodesign-poster-v2-install.XXXXXX)"
python3 -I "$RELEASE_A/package_agent_skills.py" install \
  --archive "$RELEASE_A/autodesign-poster-0.2.0-rc1.zip" \
  --checksum "$RELEASE_A/autodesign-poster-0.2.0-rc1.zip.sha256" \
  --destination "$INSTALL_ROOT"
chmod -R a-w "$INSTALL_ROOT/autodesign-poster"
```

--------------------------------

### Set DESTINATION for Codex skills

Source: https://github.com/yaxin9luo/autodesign/blob/main/agent_skills/README.md

Sets the destination directory for Codex user skills. Use this value for DESTINATION in the Quick install shell. After installation, start a new Codex task if the skills do not appear immediately.

```bash
DESTINATION="$HOME/.agents/skills"
```

--------------------------------

### Python unittest: launch documentation contract tests

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-agent-skills-launch.md

Defines the documentation contract tests for the launch page. Verifies the News row links directly to ./agent_skills/README.md and that the guide contains all approved skills and required phrases. These tests are expected to fail initially (RED) before the documentation is updated.

```python
def test_news_links_directly_to_agent_skills_readme(self):
    news = ROOT_README.read_text(encoding="utf-8")
    self.assertRegex(news, r"2026-08-17.*\./agent_skills/README\.md")

def test_launch_guide_is_installable_and_honest(self):
    guide = SKILLS_README.read_text(encoding="utf-8")
    for skill in APPROVED_SKILLS:
        self.assertIn(skill, guide)
    for phrase in ("gh skill install", "70–80%", "does not replace", "Contributing"):
        self.assertIn(phrase, guide)
```

--------------------------------

### Claim/source map JSON example

Source: https://github.com/yaxin9luo/autodesign/blob/main/agent_skills/autodesign-poster/references/output-contract.md

Use this JSON structure to define claims with their source IDs. Each claim must have exactly the keys 'id', 'text', and 'source_ids'. The 'id' must appear exactly once in visible HTML, and the visible text must match the mapped text.

```json
{"claims":[{"id":"claim-method-01","source_ids":["paper-sec-method"],"text":"The routing stage uses two passes."}]}
```

--------------------------------

### Set DESTINATION for Claude Code skills

Source: https://github.com/yaxin9luo/autodesign/blob/main/agent_skills/README.md

Sets the destination directory for Claude Code personal skills. Set this in the same shell before running the Quick install loop; the loop preserves a destination you already selected. Restart Claude Code if this is the first Skill directory on the machine.

```bash
DESTINATION="$HOME/.claude/skills"
```

--------------------------------

### Crop request JSON example

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/specs/2026-08-17-poster-agent-first-v2-design.md

Example crop request JSON. The Agent selects a one-based page and a normalized top-left-origin bounding box. The crop command verifies the exact page manifest and performs no semantic approval.

```json
{
  "page": 7,
  "bbox": [0.12, 0.18, 0.84, 0.71],
  "kind": "figure",
  "poster_role": "method-overview",
  "supports_claims": ["claim-method-01"],
  "why_essential": "The paper's principal system diagram"
}
```

--------------------------------

### Build review payload for PDF visual review

Source: https://github.com/yaxin9luo/autodesign/blob/main/agent_skills/autodesign-webpage/references/output-contract.md

Constructs the JSON payload for a fresh host VLM review, including SHA-256 hashes for the source manifest, visuals, and candidate evidence. Confidence must be a finite number from 0.8 through 1. Use the exact reviewer_mode accepted by _portable.py and generate from the current catalog, not this example.

```json
{
  "reviewer_mode": "fresh_host_vlm",
  "source_manifest_sha256": "...",
  "source_visuals_sha256": "...",
  "matches": [{
    "visual_id": "vis-001",
    "visual_sha256": "...",
    "caption_evidence_id": "ev-042",
    "caption_evidence_sha256": "...",
    "confidence": 0.93,
    "allowed_content_roles": ["overview", "method"]
  }]
}
```

--------------------------------

### Transition wipe clip with bars and rule

Source: https://github.com/yaxin9luo/autodesign/blob/main/prompts/hyperframes_composer.md

Adds a transition clip between adjacent scenes. data-start is scene N start + duration - 1.15s. Use first palette color for .bar and second for .rule.

```html
<div id="tr-1" class="clip transition"
     data-start="8.5" data-duration="0.9"
     data-track-index="21"
     data-layout-ignore>
  <div class="bar"></div>
  <div class="rule"></div>
</div>
```

--------------------------------

### Narration audio element for editable project

Source: https://github.com/yaxin9luo/autodesign/blob/main/agent_skills/autodesign-video/references/output-contract.md

Single narration audio element required before delivery. Uses the clip class and fixed attributes: start at 0, duration 360, track index 2, and media start 0. The audio file is assets/narration.wav.

```html
<audio class="clip" src="assets/narration.wav"
       data-start="0" data-duration="360"
       data-track-index="2" data-media-start="0"></audio>
```

--------------------------------

### Hash-bound review object JSON

Source: https://github.com/yaxin9luo/autodesign/blob/main/agent_skills/autodesign-ppt/references/review-rubric.md

JSON object to write for a review, copying binding fields exactly from qa/review-context.json. The example shows an abbreviated review; reviewed_frame_ids must equal the sorted complete frame set from the context. Use needs_visual_review if the host has no vision.

```json
{
  "format_version": 1,
  "attempt_id": "01",
  "review_context_sha256": "...",
  "artifact_hashes": {"artifact/deck.html": "..."},
  "preview_hashes": {"contact-sheet": "...", "slide-01": "..."},
  "reviewed_frame_ids": ["contact-sheet", "slide-01"],
  "source_manifest_sha256": "...",
  "rubric_sha256": "...",
  "source_map_sha256": "...",
  "reviewer_mode": "fresh_subagent",
  "dimension_scores": {
    "source_fidelity": 4,
    "narrative_coherence": 4,
    "visual_hierarchy": 4,
    "typography_legibility": 4,
    "layout_composition": 4,
    "evidence_communication": 4,
    "speaker_notes": 4
  },
  "blockers": [],
  "localized_repairs": [],
  "verdict": "pass",
  "complete": true
}
```

--------------------------------

### Output contract v4: reference_style_analysis.json schema

Source: https://github.com/yaxin9luo/autodesign/blob/main/skills/poster/reference_style_extraction/references/output_contract_v4.md

Defines the reference_style_analysis.json contract: every field uses measured values from reference.png, and placeholder values like #RRGGBB and 0 must be replaced. Observed booleans and arrays (e.g., region_count, region_boxes) must reflect the actual image, not the example lengths.

```json
{
  "version": 4,
  "transfer_mode": "reference_first_reconstruction",
  "summary": "short visual description",
  "palette": {
    "background": "#RRGGBB", "ink": "#RRGGBB", "primary": "#RRGGBB",
    "secondary": "#RRGGBB", "accent": "#RRGGBB",
    "header_text": "#RRGGBB", "section_heading_text": "#RRGGBB",
    "additional_roles": {"optional_repeated_accent_role": "#RRGGBB"}
  },
  "header_treatment": {
    "mode": "open_white|top_rule_white|tinted_open|filled_band|subtle_outline|split_identity",
    "alignment": "left|center",
    "composition": "full_width_identity|left_identity_cluster|centered_identity",
    "background_role": "background|secondary|primary",
    "title_color_role": "primary|ink|header_text",
    "rule_placement": "none|top|bottom", "rule_color_role": "primary|ink",
    "rule_width_px": 0
  },
  "lead_band": {
    "present": true, "placement": "below_identity",
    "background_role": "primary|secondary|accent",
    "text_color_role": "on_primary|ink", "alignment": "left|center",
    "height_px": 0, "text_size_px": 0
  },
  "section_heading_treatment": {
    "mode": "filled_band|outlined_band|underline|text_only",
    "text_color_role": "primary|ink|on_primary",
    "fill_role": "background|secondary|primary", "border_role": "primary|ink",
    "border_width_px": 0, "corner_style": "square|rounded|capsule",
    "rule_color_role": "primary|ink", "rule_width_px": 0
  },
  "section_structure": {
    "inter_section_dividers": "none|hairline|strong",
    "outer_border": "none|hairline",
    "vertical_accent_rules": "none|sparse|frequent"
  },
  "body_region_structure": {
    "layout_mode": "equal_regions|weighted_regions|freeform_regions",
    "region_count": 3,
    "major_section_count": 3,
    "major_sections_per_region": [1, 1, 1],
    "regions": [
      {
        "region_id": "region_1",
        "region_role": "column|footer_band|side_callout|hero_region|stacked_region|full_width_band",
        "section_count": 1,
        "reading_order": 1
      }
    ],
    "subsection_treatment": "inline_colored_label|small_heading|none"
  },
  "surfaces": {
    "panel_fill": "white|near_white|transparent",
    "border_style": "none|hairline",
    "corner_style": "square|subtle", "shadow_style": "none|subtle"
  },
  "spacing": {
    "outer_margin_px": 0, "column_gap_px": 0,
    "section_gap_px": 0, "panel_padding_px": 0
  },
  "layout_rhythm": {
    "region_proportions": [1, 1, 1],
    "density": "dense|balanced",
    "region_boxes": [
      {"region_id": "region_1", "x_pct": 0, "y_pct": 0, "w_pct": 33, "h_pct": 100}
    ]
  },
  "chrome_treatment": {
    "present": false, "placement": "none|gutters|section_edges",
    "density": "none|sparse|frequent", "crossing_policy": "never_cross_content"
  },
  "typography_style": {
    "display_family_category": "sans_serif|serif",
    "body_family_category": "sans_serif|serif",
    "family_category": "sans_serif|serif",
    "title_weight": 700, "identity_weight": 500,
    "section_heading_weight": 700, "body_weight": 400,
    "title_size_px": 72, "identity_size_px": 26,
    "section_heading_size_px": 34, "body_size_px": 24, "caption_size_px": 20
  },
  "table_treatment": {
    "observed": false,
    "rule_style": "none|minimal|booktabs|hairline_grid",
    "header_fill": "none|light|primary"
  },
  "formula_treatment": {"frame": "none|hairline|box", "background": "none|light"},
  "figure_treatment": {"frame": "none|hairline", "caption_alignment": "left|center"},
  "do_not_copy": ["reference content", "reference logos", "reference figures"]
}
```

--------------------------------

### Set up the run with webpage_harness.py

Source: https://github.com/yaxin9luo/autodesign/blob/main/agent_skills/autodesign-webpage/SKILL.md

Sets up a run: runs doctor, initializes the run directory with the paper source, checks status, prints the status JSON, and extracts the active attempt ID.

```bash
HARNESS="$SKILL_ROOT/scripts/webpage_harness.py"
python3 "$HARNESS" doctor
python3 "$HARNESS" init --run-dir "$RUN_DIR" --source "$PAPER"
STATUS_JSON="$(python3 "$HARNESS" status --run-dir "$RUN_DIR")"
printf '%s\n' "$STATUS_JSON"
ATTEMPT_ID="$(printf '%s' "$STATUS_JSON" | python3 -c 'import json,sys; print(json.load(sys.stdin)["active_attempt"] or "")')"
```

--------------------------------

### Build release A and B and verify deterministic output

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-agent-skills-launch.md

Builds two release directories (A and B) and compares them with diff -qr. Expects no diff; each release contains four ZIPs, four checksum sidecars, manifest.json, and the two release-local tools.

```bash
python3 -B scripts/package_agent_skills.py build --source-root agent_skills --output-dir /tmp/autodesign-skills-v0.1.0-a --version 0.1.0
python3 -B scripts/package_agent_skills.py build --source-root agent_skills --output-dir /tmp/autodesign-skills-v0.1.0-b --version 0.1.0
diff -qr /tmp/autodesign-skills-v0.1.0-a /tmp/autodesign-skills-v0.1.0-b
```

--------------------------------

### Run sync and tests

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-poster-agent-first-v2.md

Commands to sync the skill core, run the unit tests, check for drift, and verify the diff.

```bash
PYTHONDONTWRITEBYTECODE=1 python3 scripts/sync_agent_skill_core.py
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest \
  tests.test_portable_png \
  tests.test_portable_skill_run_state \
  tests.test_portable_agent_skill_packages -v
PYTHONDONTWRITEBYTECODE=1 python3 scripts/sync_agent_skill_core.py --check
git diff --check
```

--------------------------------

### Run v2 initialization and inspect/diagnose tests

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-poster-agent-first-v2.md

Runs the RED tests for v2 initialization and fail-closed inspect/diagnose behavior. Expected to fail because v2 argument/constants/functions are missing.

```bash
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest \
  tests.test_portable_source_curation_v2.PortableSourceCurationV2Tests.test_v2_initialization_is_explicit_and_v1_default_is_unchanged \
  tests.test_portable_source_curation_v2.PortableSourceCurationV2Tests.test_inspect_and_diagnose_are_fail_closed_and_read_only -v
```

--------------------------------

### Initialize poster run with agent-first format

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-poster-agent-first-v2.md

Calls core.initialize_run with the agent-first run format version, replacing the previous initialization logic.

```python
core.initialize_run(
    run_dir,
    SKILL_ROOT,
    release_version=release_version,
    archive_sha256=archive_sha256,
    run_format_version=core.AGENT_FIRST_RUN_FORMAT_VERSION,
)
```

--------------------------------

### CLI help output for v2 commands

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-poster-agent-first-v2.md

Expected output of the --help flag, listing all v2 commands including doctor, init, evidence, and lifecycle commands.

```text
doctor init evidence inspect-source crop-source list-source-assets
source-review-context record-source-review plan begin-attempt dom-audit
validate review-context record-review reopen-curation finalize resume diagnose-v1
```

--------------------------------

### Build release archives for agent skills

Source: https://github.com/yaxin9luo/autodesign/blob/main/agent_skills/README.md

Run this command to build deterministic, non-overwriting release archives. It specifies the source root, output directory, and version. The output directory will contain versioned ZIP and SHA-256 sidecar files per Skill, manifest.json, and the release-local tools. Build twice and compare every byte before publishing.

```bash
python3 -B scripts/package_agent_skills.py build \
  --source-root agent_skills \
  --output-dir dist/agent-skills-v0.2.0 \
  --version 0.2.0
```

--------------------------------

### Create plan with plan command

Source: https://github.com/yaxin9luo/autodesign/blob/main/agent_skills/autodesign-webpage/SKILL.md

Creates the plan from plan.json. The plan must include the paper identity, thesis, abstract, method, evidence, results, limitations, resources, citation, and at least one source-bound inspect or compare interaction.

```bash
python3 "$HARNESS" plan --run-dir "$RUN_DIR" --plan-json plan.json
```

--------------------------------

### Expected Catalog Files

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-poster-agent-first-v2.md

Lists the exact files that must be atomically created by a passing review, including catalog.json, review.json, manifest.json, and COMMIT.json.

```text
curations/001/catalog.json
curations/001/review.json
curations/001/manifest.json
curations/001/COMMIT.json
```

--------------------------------

### Review and commit: verify hashes, stage, and commit

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-poster-agent-first-v2.md

Commands to verify byte-identical core hashes, stage the canonical core and synced copies, check staged changes, and commit. Stage only the canonical core, four mechanically synced copies, and the two owned test files.

```bash
shasum -a 256 agent_skills/_shared/portable_core.py \
  agent_skills/autodesign-{poster,ppt,webpage,video}/scripts/_portable.py
git add agent_skills/_shared/portable_core.py \
  agent_skills/autodesign-{poster,ppt,webpage,video}/scripts/_portable.py \
  tests/test_portable_source_curation_v2.py \
  tests/test_portable_skill_run_state.py
git diff --cached --check
git commit -m "feat(skills): add opt-in Agent-first source runs"
```

--------------------------------

### Run verification commands

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-poster-agent-first-v2.md

Commands to run unit tests and sync the agent skill core. The first command runs the v2 tests, the second syncs the core, and the third runs the skill tests.

```bash
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest \
  tests.test_portable_source_curation_v2 \
  tests.test_autodesign_poster_agent_first_v2 \
  tests.test_portable_skill_run_state -v
```

```bash
PYTHONDONTWRITEBYTECODE=1 python3 scripts/sync_agent_skill_core.py
```

```bash
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest \
  tests.test_autodesign_ppt_skill \
  tests.test_autodesign_webpage_skill \
  tests.test_autodesign_video_skill -v
```

```bash
git diff --check
```

--------------------------------

### Reproducible Codex CLI invocation for acceptance run

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-poster-agent-first-v2.md

Runs one native Codex trajectory per paper in a clean workspace using the installed autodesign-poster Skill. Requires workspace-write sandbox, approval, and JSON output; the command must be run from an empty non-repository workspace.

```bash
paper_id="autodesign"
CODEX_HOME="$ACCEPTANCE_ROOT/codex-home" \
codex exec --sandbox workspace-write --approve-for-me --skip-git-repo-check \
  --cd "$ACCEPTANCE_ROOT/work/$paper_id" --json \
  --output-last-message "$ACCEPTANCE_ROOT/work/$paper_id/last-message.txt" \
  'Use $autodesign-poster to turn paper.pdf into a dense, editable, source-grounded conference poster. Inspect the PDF directly, perform fresh source review, iterate through every required validation/review route, and finalize only a passing artifact.' \
  > "$ACCEPTANCE_ROOT/work/$paper_id/trajectory.jsonl"
```

--------------------------------

### Run focused package and packaging tests

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-agent-skills-launch.md

Runs focused unit tests for portable agent skill packages and packaging. Expects 17 or more tests to pass with no failures.

```bash
PYTHONDONTWRITEBYTECODE=1 python3 -B -m unittest \
  tests.test_portable_agent_skill_packages \
  tests.test_portable_agent_skill_packaging -v
```

--------------------------------

### Run full evaluation with run_poster_benchmark_main_table.py

Source: https://github.com/yaxin9luo/autodesign/blob/main/eval/README.md

Runs the complete evaluation with multiple workers (--workers 4) using the gemini-3.5-flash model. Supports multiple systems using a comma-separated --systems list and corresponding --*-root arguments.

```bash
uv --cache-dir .uv-cache run --extra ocr \
  python scripts/run_poster_benchmark_main_table.py \
  --paper-root eval/EvaData \
  --systems codex_native \
  --codex-native-root /absolute/path/to/candidates \
  --system-label "codex_native=Your System" \
  --model gemini-3.5-flash \
  --workers 4 \
  --out-dir out/eval/your-system
```

--------------------------------

### Build deterministic release twice and diff

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-poster-agent-first-v2.md

Bash commands to create two deterministic release archives and verify they are identical using diff. Used in Step 3 to prove portable packaging.

```bash
RELEASE_A="$(mktemp -d /tmp/autodesign-poster-v2-release-a.XXXXXX)"
RELEASE_B="$(mktemp -d /tmp/autodesign-poster-v2-release-b.XXXXXX)"
python3 -I scripts/package_agent_skills.py build \
  --source-root agent_skills \
  --output-dir "$RELEASE_A" \
  --version 0.2.0-rc1
python3 -I scripts/package_agent_skills.py build \
  --source-root agent_skills \
  --output-dir "$RELEASE_B" \
  --version 0.2.0-rc1
diff -qr "$RELEASE_A" "$RELEASE_B"
```

--------------------------------

### Run shared and v1 regression suites, then sync

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-poster-agent-first-v2.md

Commands to run v2 and v1 regression tests, sync the agent skill core, check for sync drift, and verify no whitespace errors. Expected: v2 tests pass and all three non-Poster Skills remain released-v1 green.

```bash
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest \
  tests.test_portable_source_curation_v2 \
  tests.test_portable_skill_run_state -v
PYTHONDONTWRITEBYTECODE=1 python3 scripts/sync_agent_skill_core.py
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest \
  tests.test_autodesign_ppt_skill \
  tests.test_autodesign_webpage_skill \
  tests.test_autodesign_video_skill -v
PYTHONDONTWRITEBYTECODE=1 python3 scripts/sync_agent_skill_core.py --check
git diff --check
```

--------------------------------

### Download AutoDesign skills release with GitHub CLI

Source: https://github.com/yaxin9luo/autodesign/blob/main/agent_skills/README.md

Downloads the checksum-verified release bundle for AutoDesign agent skills using GitHub CLI. Creates a directory, downloads the release, and changes into it.

```bash
mkdir -p autodesign-skills-v0.2.0
gh release download agent-skills-v0.2.0 \
  --repo Yaxin9Luo/AutoDesign \
  --dir autodesign-skills-v0.2.0
cd autodesign-skills-v0.2.0
```

--------------------------------

### Run crop registry RED tests

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-poster-agent-first-v2.md

Runs the RED tests for crop registry behavior, including missing hints, idempotency, and fail-closed behavior. Expected to fail because crop APIs are absent.

```bash
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest \
  tests.test_portable_source_curation_v2.PortableSourceCurationV2Tests.test_agent_can_register_crop_missing_from_pdfimages_hints \
  tests.test_portable_source_curation_v2.PortableSourceCurationV2Tests.test_crop_registry_is_hash_bound_idempotent_and_append_only \
  tests.test_portable_source_curation_v2.PortableSourceCurationV2Tests.test_crop_registry_fails_closed_without_outside_mutation -v
```

--------------------------------

### Download benchmark papers (small or full split)

Source: https://github.com/yaxin9luo/autodesign/blob/main/eval/README.md

Downloads the fixed 10-paper development subset or the full 100-paper corpus. The downloader is strict: it only downloads papers with an HTTPS PDF URL, an approved license, and a matching SHA-256.

```bash
# Fixed 10-paper development subset
uv --cache-dir .uv-cache run python scripts/download_benchmark_papers.py \
  --split small

# Full 100-paper benchmark
uv --cache-dir .uv-cache run python scripts/download_benchmark_papers.py \
  --split full
```

--------------------------------

### Run mapping preflight check with run_poster_benchmark_main_table.py

Source: https://github.com/yaxin9luo/autodesign/blob/main/eval/README.md

Checks candidate-to-paper mapping before making any model calls. Review case_mapping.csv and resolve missing, duplicate, or incorrect mappings before scoring.

```bash
uv --cache-dir .uv-cache run --extra ocr \
  python scripts/run_poster_benchmark_main_table.py \
  --paper-root eval/EvaData \
  --systems codex_native \
  --codex-native-root /absolute/path/to/candidates \
  --system-label "codex_native=Your System" \
  --dry-map \
  --out-dir out/eval/your-system
```

--------------------------------

### Run RED tests for portable_png

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-poster-agent-first-v2.md

Command to run the unit tests for the portable_png module, expecting import/file-not-found failures because portable_png.py does not exist yet.

```bash
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest tests.test_portable_png -v
```

--------------------------------

### Transition Overlay CSS

Source: https://github.com/yaxin9luo/autodesign/blob/main/prompts/hyperframes_composer.md

Creates a full-screen transition overlay with a background bar and a thin rule. Uses CSS custom properties for colors.

```css
.transition {
  position: absolute;
  inset: 0;
  z-index: 50;
  overflow: hidden;
  pointer-events: none;
}
.transition .bar {
  position: absolute;
  inset: 0;
  background: var(--bar-color);   /* first palette color */
  transform-origin: left center;
}
.transition .rule {
  position: absolute;
  top: 0; bottom: 0;
  width: 8px;
  background: var(--rule-color);  /* second palette color */
}
```

--------------------------------

### Run all four package validators

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-agent-skills-launch.md

Runs all four package validators (Poster, PPT, Webpage, Video). Each validator should print OK.

```bash
PYTHONDONTWRITEBYTECODE=1 python3 -B scripts/validate_agent_skills.py --root agent_skills
```

--------------------------------

### Git: commit public launch docs

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-agent-skills-launch.md

Commits the public launch documentation after the focused tests pass (GREEN). Adds the root README and the dedicated agent_skills README.

```bash
git add README.md agent_skills/README.md
git commit -m "docs(skills): publish standalone install guide"
```

--------------------------------

### Load PosterBench datasets from Hugging Face

Source: https://github.com/yaxin9luo/autodesign/blob/main/eval/README.md

Loads the benchmark metadata-only datasets from Hugging Face. The license covers only metadata and annotations, not the underlying papers.

```python
from datasets import load_dataset

posterbench = load_dataset("YaxinLuo/PosterBench", split="test")
posterbench_mini = load_dataset("YaxinLuo/PosterBench-mini", split="test")
```

--------------------------------

### Generate a paper poster with autodesign run

Source: https://github.com/yaxin9luo/autodesign/blob/main/README.md

Generate a paper poster. Inspect final/poster.html, final/preview.png, the final manifest, and run_events.jsonl. A file can exist after a fallback, so terminal status and validation feedback remain part of the result.

```bash
uv --cache-dir .uv-cache run python -m autodesign run \
  "Create a dense academic conference poster from the attached paper." \
  --from-file /absolute/path/to/paper.pdf \
  --template cvpr-landscape
```

--------------------------------

### Verification Commands

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-poster-agent-first-v2.md

Commands to run unit tests, sync agent skill core, validate agent skills, and check git diff for whitespace errors.

```bash
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest \
  tests.test_portable_source_curation_v2 -v
PYTHONDONTWRITEBYTECODE=1 python3 scripts/sync_agent_skill_core.py
PYTHONDONTWRITEBYTECODE=1 python3 scripts/sync_agent_skill_core.py --check
PYTHONDONTWRITEBYTECODE=1 python3 scripts/validate_agent_skills.py --root agent_skills
git diff --check
```

--------------------------------

### Run final clean-tree verification and commit report

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-poster-agent-first-v2.md

Runs the full deterministic test suite, smoke tests, skill validations, and git checks before force-adding the acceptance report. The command sequence verifies the clean tree and commits the report only after all gates pass.

```bash
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest \
  tests.test_portable_png \
  tests.test_portable_source_curation_v2 \
  tests.test_autodesign_poster_agent_first_v2 \
  tests.test_poster_dom_audit \
  tests.test_autodesign_poster_skill \
  tests.test_portable_skill_run_state \
  tests.test_portable_agent_skill_packages \
  tests.test_portable_agent_skill_packaging \
  tests.test_autodesign_ppt_skill \
  tests.test_autodesign_webpage_skill \
  tests.test_autodesign_video_skill -v
PYTHONDONTWRITEBYTECODE=1 python3 -m autodesign.smoke
PYTHONDONTWRITEBYTECODE=1 python3 scripts/sync_agent_skill_core.py --check
PYTHONDONTWRITEBYTECODE=1 python3 scripts/validate_agent_skills.py --root agent_skills
git diff --check
git status --short
```

```bash
git add -f docs/superpowers/reports/2026-08-17-poster-agent-first-v2-acceptance.md
git diff --cached --check
git commit -m "test(skills): document Poster v2 acceptance"
```

--------------------------------

### Attempt directory structure

Source: https://github.com/yaxin9luo/autodesign/blob/main/agent_skills/autodesign-webpage/references/output-contract.md

Shows the required directory layout for a passing attempt, including artifact, provenance, and qa subdirectories with their expected files. The final directory must contain the exact reviewed artifact closure, provenance/source-map.json, and delivery-manifest.json.

```text
attempts/<id>/
  artifact/
    index.html
    assets/...
    webpage-validation.json
    browser-audit.json
    interaction-audit.json
  provenance/source-map.json
  qa/
    deterministic.json
    review-context.json
    semantic-review.json
    previews/desktop.png
    previews/mobile.png
```

--------------------------------

### Capture released baseline (bash)

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-poster-agent-first-v2.md

Run the full test suite, validators, and sync check to capture the released baseline. Expect all tests and validators to pass, sync to report `checked 4`, and no tracked or ignored bytecode under `agent_skills/`.

```bash
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest \
  tests.test_portable_skill_run_state \
  tests.test_autodesign_poster_skill \
  tests.test_autodesign_ppt_skill \
  tests.test_autodesign_webpage_skill \
  tests.test_autodesign_video_skill -v
PYTHONDONTWRITEBYTECODE=1 python3 scripts/validate_agent_skills.py --root agent_skills
PYTHONDONTWRITEBYTECODE=1 python3 scripts/sync_agent_skill_core.py --check
git status --short
```

--------------------------------

### Run format version 2 directory structure

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/specs/2026-08-17-poster-agent-first-v2-design.md

Directory layout for Agent-first runs using run format version 2. Shows the required subdirectories for input, evidence, source assets, reviews, curations, plans, attempts, and final output, plus the run.json and events.jsonl files.

```text
RUN/
  input/
    source.pdf
  evidence/
    pages/page-0001.png
    page-manifest.json
    pdfimages-hints.json
  source-assets/
    files/asset-0001.png
    receipts/asset-0001.json
  source-reviews/
    review-0001/context.json
    review-0001/review.json
  curations/
    001/catalog.json
    001/COMMIT.json
    002/catalog.json
    002/COMMIT.json
  plans/
    001/poster-plan.json
    001/COMMIT.json
    002/poster-plan.json
    002/COMMIT.json
  attempts/
    01/attempt-context.json
    01/catalog-snapshot.json
    01/plan-snapshot.json
    01/artifact/
    01/qa/dom-audit.json
    01/qa/deterministic.json
    01/qa/semantic-review.json
    02/...
  final/
  run.json
  events.jsonl
```

--------------------------------

### plan --visual-allocations JSON list

Source: https://github.com/yaxin9luo/autodesign/blob/main/agent_skills/autodesign-ppt/references/output-contract.md

Pass a JSON list of visual allocations to the `plan` command using the `--visual-allocations` flag when source visuals are needed. Each object specifies a visual ID, its role, and the slide ID where it should appear. The visual must be eligible for that role, stay within its catalog reuse limit, and appear on the allocated slide.

```json
[
  {"visual_id": "visual-explicit-001", "role": "method", "slide_id": "slide-08"}
]
```

--------------------------------

### Create source-map claims and validate attempt

Source: https://github.com/yaxin9luo/autodesign/blob/main/agent_skills/autodesign-webpage/SKILL.md

Generates the source-map claims JSON from claims.json and then validates the attempt. Validation is deterministic-first and renders desktop/mobile screenshots in a pinned offline Chromium runtime.

```bash
python3 "$HARNESS" source-map --run-dir "$RUN_DIR" --attempt "$ATTEMPT_ID" --claims-json claims.json
python3 "$HARNESS" validate --run-dir "$RUN_DIR" --attempt "$ATTEMPT_ID"
```

--------------------------------

### Generate review context

Source: https://github.com/yaxin9luo/autodesign/blob/main/agent_skills/autodesign-webpage/SKILL.md

Runs the harness review-context command to produce review-context.json for the given run directory and attempt ID.

```bash
python3 "$HARNESS" review-context --run-dir "$RUN_DIR" --attempt "$ATTEMPT_ID" > review-context.json
```

--------------------------------

### HTML: Reference figure from assets/figures/

Source: https://github.com/yaxin9luo/autodesign/blob/main/prompts/hyperframes_composer.md

Standard way to reference any figure in the assets/figures/ directory. Replace <filename> with the actual file name.

```html
<img src="assets/figures/<filename>.png" alt="..." />
```

--------------------------------

### Record review and finalize attempt

Source: https://github.com/yaxin9luo/autodesign/blob/main/agent_skills/autodesign-webpage/SKILL.md

Records the review JSON and then finalizes the attempt. Only run finalize after a passing, hash-current review.

```bash
python3 "$HARNESS" record-review --run-dir "$RUN_DIR" --attempt "$ATTEMPT_ID" --review-json review.json
```

```bash
python3 "$HARNESS" finalize --run-dir "$RUN_DIR" --attempt "$ATTEMPT_ID"
```

--------------------------------

### Confirm repository and branch (bash)

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-poster-agent-first-v2.md

Run from the repository root to verify the branch, clean tree, and recent design commits. Expect branch `codex/poster-agent-first-v2`, a clean tree, and design commits `2be9010` and `4c90c64` in history.

```bash
cd /Users/yaxinluo/Desktop/AutoDesign-public-release-ready-20260813
git status --short --branch
git rev-parse --show-toplevel
git log -3 --oneline
```

--------------------------------

### Verify benchmark manifests without downloading

Source: https://github.com/yaxin9luo/autodesign/blob/main/eval/README.md

Validates the manifests and inspects the local corpus without making network requests. Use this to check file hashes after manually obtaining papers.

```bash
uv --cache-dir .uv-cache run python scripts/download_benchmark_papers.py \
  --split small \
  --verify-only
```

--------------------------------

### Run tests and smoke checks

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-poster-agent-first-v2.md

Runs unit tests and smoke checks with bytecode writing disabled, then checks for whitespace errors.

```bash
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest \
  tests.test_autodesign_poster_agent_first_v2 \
  tests.test_autodesign_poster_skill -v
PYTHONDONTWRITEBYTECODE=1 python3 -m autodesign.smoke
git diff --check
```

--------------------------------

### Generate poster with visual reference

Source: https://github.com/yaxin9luo/autodesign/blob/main/README.md

Use a visual reference for the poster. Reference posters transfer visual systems only; their text, claims, logos, QR codes, figures, tables, and links never become paper evidence.

```bash
uv --cache-dir .uv-cache run python -m autodesign run \
  "Create a paper poster using the reference's visual system." \
  --from-file /absolute/path/to/paper.pdf \
  --reference-poster /absolute/path/to/reference.png
```

--------------------------------

### Run AutoDesign Harness with run ID capture

Source: https://github.com/yaxin9luo/autodesign/blob/main/docs/superpowers/plans/2026-08-17-poster-agent-first-v2.md

Runs the current repository Harness command for a paper, capturing its printed run ID. Requires the paper PDF path and uses the cvpr-landscape template with the codex designer. The command logs output to a command.log file.

```bash
mkdir -p "$ACCEPTANCE_ROOT/harness/$paper_id"
uv --cache-dir .uv-cache run python -m autodesign.cli run \
  --from-file "$paper_pdf" \
  --template cvpr-landscape \
  --designer-author external \
  --designer-author-harness codex \
  --designer-author-max-attempts 4 \
  'Create a dense, editable, source-grounded academic conference poster. Preserve the paper identity, central method, primary results, and original evidence.' \
  2>&1 | tee "$ACCEPTANCE_ROOT/harness/$paper_id/command.log"
```

--------------------------------

### Write completion marker file

Source: https://github.com/yaxin9luo/autodesign/blob/main/skills/poster/reference_style_extraction/references/output_contract_v4.md

Content to write to reference_style_agent_done.json after the review passes. Signals successful completion.

```json
{"status":"ok"}
```