@design-ai/cli 4.55.0

package/skills/video-designer/PLAYBOOK.md

@@ -0,0 +1,240 @@
+# video-designer — playbook
+
+Design and spec video for marketing, social, or in-product use. Output is a production-ready video spec a producer / videographer / editor can deliver against.
+
+## When to use
+
+- "Design the hero video for our landing page."
+- "Spec a 60-second product demo."
+- "Plan a YouTube Shorts campaign."
+- "What captions / formats do we need?"
+- "Spec the onboarding video for our app."
+
+## Inputs (ask if missing)
+
+1. **Surface** — landing-page hero / brand film / product demo / onboarding / help video / short-form social / ad spot.
+2. **Platform** — YouTube / Reels / Shorts / TikTok / website / in-app / OOH.
+3. **Length** — desired duration.
+4. **Audience** — Korean / international / mixed; B2C / B2B; age range.
+5. **Brand voice** — Toss-style / playful / formal / cinematic.
+6. **Production budget** — DIY / indie / production-company / TVCM-tier.
+7. **Audio strategy** — voiceover / music-only / silent autoplay.
+8. **Existing assets** — existing footage, brand video, music library.
+
+## Steps
+
+### 1. Classify the video
+
+| Type | Read |
+| --- | --- |
+| Hero loop, brand film, demo, ad | [`marketing-video.md`](../../knowledge/video/marketing-video.md) |
+| Reels / Shorts / TikTok / vertical | [`social-and-short-form.md`](../../knowledge/video/social-and-short-form.md) |
+| Onboarding, help, changelog | [`in-product-video.md`](../../knowledge/video/in-product-video.md) |
+| Korean market specifics | [`korean-video-conventions.md`](../../knowledge/video/korean-video-conventions.md) |
+
+Always also: [`video-fundamentals.md`](../../knowledge/video/video-fundamentals.md).
+
+### 2. Spec the technical format
+
+| Spec | Decide |
+| --- | --- |
+| Resolution | 1080p default; 4K master if reframing needed |
+| Aspect ratio | 16:9 landscape / 9:16 vertical / 1:1 square |
+| Framerate | 30fps default; 60fps for fast UI / sports |
+| Codec | H.264 (compatibility) + H.265 / AV1 (size); WebM for web |
+| Audio | AAC 128-256 kbps; -14 LUFS for online |
+| Captions | WebVTT or burned-in (specify language tracks) |
+| File size | Target by use: < 5MB hero loop, < 50MB demo |
+
+### 3. Pick length
+
+| Use | Length |
+| --- | --- |
+| Hero loop autoplay | 5-15s |
+| Product demo | 30-90s |
+| Brand film | 60-180s |
+| Onboarding video | 30-90s |
+| Help video | 30-120s |
+| Reels / Shorts | 15-60s |
+| TikTok | 15-60s (up to 3min, 10min) |
+| YouTube long-form | varies |
+| TVCM | 15s, 30s, 60s spots |
+
+Cut to shortest that conveys the message. Default: **shorter than the obvious answer**.
+
+### 4. Spec the script structure
+
+For long-form (60+ seconds):
+```
+0:00-0:05  Hook (1-second-grade attention grab)
+0:05-0:20  Problem (what users face)
+0:20-0:50  Solution (your product / value)
+0:50-end   CTA (try it, sign up, learn more)
+```
+
+For short-form (15-30s):
+```
+0:00-0:01  Hook (must stop scroll)
+0:01-end   Single message / single demo
+0:end-1s   CTA / brand mark
+```
+
+For hero loop (5-15s):
+```
+0:00       Calm starting frame
+0:05       Peak action (the "wow" beat)
+0:end      Settle to start frame (loop)
+```
+
+### 5. Captions / subtitles
+
+| Use | Captions |
+| --- | --- |
+| Hero loop (silent autoplay) | None needed (no audio) |
+| Brand film / demo | WebVTT, multi-language |
+| Social short-form | Burned-in (open captions) — 80% watch muted |
+| In-product | WebVTT toggle, default ON |
+| Korean any platform | Korean subtitle always |
+
+Style:
+- Bottom 10-20% of frame.
+- White text + black outline OR brand color.
+- Sans-serif, condensed (Pretendard / NanumSquare for Korean).
+- Max 2 lines, ≤ 32 chars per line.
+
+### 6. Voiceover (if applicable)
+
+| Choice | Use |
+| --- | --- |
+| Korean female gentle | Toss-style fintech, beauty |
+| Korean female professional | B2B, education |
+| Korean male warm | Premium consumer, automotive |
+| English voiceover | International primary |
+| AI voice (Clova, ElevenLabs) | Short-form, changelogs, low-stakes |
+| Human voiceover | Brand-critical, ads, hero |
+
+Honorific level (Korean):
+- 합쇼체 (~합니다) for B2B, banking, formal.
+- 해요체 (~해요) for B2C, lifestyle, fintech (default 2024+).
+
+### 7. Music + sound
+
+| Source | Use |
+| --- | --- |
+| Royalty-free libraries (Epidemic, Artlist, Musicbed) | Most B2B / B2C |
+| Korean royalty-free (Audionetwork KR, Pond5 KR) | KR market |
+| Platform-native trending sound | Reels / TikTok algorithm boost |
+| Custom composition | Brand-defining campaigns |
+| K-pop tracks | Avoid — copyright |
+
+Mix loudness to **-14 LUFS** for online platforms.
+
+### 8. Korean ad disclosure (if branded)
+
+For sponsored / paid promotion:
+- YouTube: tag "Includes paid promotion" + verbal disclosure.
+- Instagram / TikTok: `#광고`, `#유료광고`, `#PR` in caption.
+- Public-facing ads: 표시광고법 compliance.
+
+For health / cosmetic / financial products: KFDA / FSC pre-approval of claims.
+
+### 9. Performance + delivery
+
+For web:
+- Provide multiple formats (WebM + MP4 H.265 + MP4 H.264).
+- Include poster for first paint.
+- `preload="auto"` for hero, `preload="metadata"` below the fold.
+- Use `<source media="...">` for art-direction (mobile vs desktop video).
+
+For platform delivery:
+- YouTube: 1080p+ at high bitrate; YouTube re-encodes.
+- Reels / Shorts / TikTok: 1080×1920 vertical at platform spec.
+- In-product: HLS adaptive bitrate for longer videos.
+
+### 10. Output
+
+Use this structure:
+
+```markdown
+# Video spec: <title>
+
+> Surface: <hero loop / brand film / demo / shorts / etc>
+> Platform: <YouTube / Reels / website / in-app>
+> Audience: <KR / international>
+> Brand voice: <...>
+> Length: <duration>
+
+## Technical specs
+| Spec | Value |
+... resolution, fps, codec, audio, captions
+
+## Script / structure
+<beat-by-beat outline>
+
+## Captions
+<language tracks, style, file format>
+
+## Voiceover
+<voice, language, honorific level>
+
+## Music
+<library / track, loudness>
+
+## Korean compliance (if applicable)
+<ad disclosure, KFDA, KFTC>
+
+## File delivery
+<formats, bitrates, file naming>
+
+## Performance budget
+<file size, LCP impact>
+
+## Accessibility
+<captions, transcripts, audio descriptions>
+
+## Don't
+<2-3 specific misuses>
+```
+
+## Source files this skill reads
+
+- [`knowledge/video/video-fundamentals.md`](../../knowledge/video/video-fundamentals.md)
+- [`knowledge/video/marketing-video.md`](../../knowledge/video/marketing-video.md)
+- [`knowledge/video/social-and-short-form.md`](../../knowledge/video/social-and-short-form.md)
+- [`knowledge/video/in-product-video.md`](../../knowledge/video/in-product-video.md)
+- [`knowledge/video/korean-video-conventions.md`](../../knowledge/video/korean-video-conventions.md)
+- [`knowledge/motion/motion-tools.md`](../../knowledge/motion/motion-tools.md) — when motion < video
+- [`knowledge/i18n/korean-document-style.md`](../../knowledge/i18n/korean-document-style.md) — honorific level
+- [`examples/component-video-player.md`](../../examples/component-video-player.md) — player spec
+- [`examples/component-video-hero.md`](../../examples/component-video-hero.md) — autoplay hero spec
+
+## Verification phase (run before declaring done)
+
+- [ ] Is the surface category explicit (hero loop / demo / shorts / onboarding / etc)?
+- [ ] Is the technical spec (resolution / fps / codec / aspect ratio) explicit?
+- [ ] Is length within range for the surface?
+- [ ] Is the script structure (hook / body / CTA) explicit?
+- [ ] Are captions specified (language tracks + format)?
+- [ ] If voiceover: is the language + tone + honorific level explicit?
+- [ ] Is loudness target (-14 LUFS for online) specified?
+- [ ] Are platform-specific constraints (Reels safe area, YouTube spec) addressed?
+- [ ] If Korean B2C: is ad disclosure + KFDA where applicable addressed?
+- [ ] Is file delivery format (multi-codec, poster, HLS) specified?
+- [ ] Is performance budget (file size, LCP impact) stated?
+- [ ] Is reduced-motion / slow-connection fallback specified for autoplay?
+- [ ] Does "Don't" section catch 2-3 specific misuses?
+
+## Done when
+
+- One markdown spec, < 400 lines.
+- Surface, platform, audience, length explicit.
+- Technical specs (resolution, fps, codec, audio, captions).
+- Script structure.
+- Captions language + format.
+- Voiceover details if applicable.
+- Music source + loudness.
+- Korean compliance if applicable.
+- File delivery format.
+- Performance + accessibility addressed.
+- "Don't" section.
+- Verification passes.

package/skills/video-designer/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: video-designer
+description: Design and spec video for marketing, social, or in-product use. Picks length, format, aspect ratio, codec, captions, voiceover, and platform; produces production-ready spec. Korean conventions and ad-disclosure rules included.
+---
+
+See [PLAYBOOK.md](PLAYBOOK.md).

package/skills/website-improvement/PLAYBOOK.md

@@ -0,0 +1,118 @@
+# website-improvement — playbook
+
+Plan and coordinate professional website improvement work for an existing site. This skill does not modify the target website repository directly; it prepares the audit, MCP readiness, task plan, prompts, and handoff report that another agent can execute in the target repo.
+
+## When to use
+
+- "Improve this homepage."
+- "Audit our website before a redesign sprint."
+- "Create a Codex prompt to refactor the pricing page."
+- "Plan MCP setup for a site improvement project."
+- "Turn website audit findings into implementation tasks."
+
+## Inputs
+
+1. **Site Profile** — name, live URL, repo URL/local path, priority pages, user flows, Figma URL, brand notes, deploy provider, Sentry, CMS, database, and target viewports.
+2. **Audit findings** — visual design, UX flow, responsive QA, accessibility, performance, SEO, technical quality, runtime issues, and content quality.
+3. **MCP readiness** — GitHub, Figma, Browser/Playwright, Chrome DevTools, deploy provider, Sentry, database, CMS, collaboration, and research status.
+4. **Execution target** — Codex for repo work, Claude for design/research/copy review, or final handoff.
+
+## Steps
+
+### 1. Establish the Site Profile
+
+Capture only operational metadata needed for planning. Do not copy private source code into design-ai. Treat Figma URLs, repo paths, Sentry project names, CMS details, and local filesystem paths as sensitive project metadata.
+
+### 2. Run the Audit Pipeline
+
+Evaluate each category and record findings:
+
+| Category | Check |
+| --- | --- |
+| Visual Design | Layout, type, color, spacing, visual hierarchy |
+| UX Flow | Navigation, CTA, forms, conversion flow, confusion points |
+| Responsive QA | Desktop, tablet, mobile layout and text wrapping |
+| Accessibility | Keyboard, focus, contrast, semantic HTML, ARIA |
+| Performance | Core Web Vitals, images, bundle size, render bottlenecks |
+| SEO | Title, description, headings, canonical, OG, sitemap |
+| Technical Quality | Component structure, style duplication, dead code, dependency risk |
+| Runtime Issues | Console errors, network errors, hydration issues, broken assets |
+| Content Quality | Copy clarity, IA, proof, trust, CTA language |
+
+Use the relevant design-ai knowledge files when making judgments:
+
+- [`knowledge/PRINCIPLES.md`](../../knowledge/PRINCIPLES.md)
+- [`knowledge/patterns/ux-guidelines.md`](../../knowledge/patterns/ux-guidelines.md)
+- [`knowledge/a11y/contrast.md`](../../knowledge/a11y/contrast.md)
+- [`knowledge/a11y/keyboard-and-focus.md`](../../knowledge/a11y/keyboard-and-focus.md)
+- [`knowledge/layout/spacing-and-grid.md`](../../knowledge/layout/spacing-and-grid.md)
+- [`knowledge/typography/type-scale-fundamentals.md`](../../knowledge/typography/type-scale-fundamentals.md)
+- [`knowledge/patterns/technical-writing.md`](../../knowledge/patterns/technical-writing.md)
+- [`knowledge/patterns/report-design.md`](../../knowledge/patterns/report-design.md)
+
+### 3. Classify MCP Readiness
+
+Set each MCP to one of:
+
+- `required` — needed before implementation or verification can be trusted.
+- `optional` — useful, but a manual fallback is acceptable.
+- `unused` — not relevant to this site/project phase.
+- `unavailable` — relevant, but not connected; mention as a risk.
+
+Do not invent live MCP results. If a tool was not actually connected and checked, state that it is readiness planning only.
+
+### 4. Generate Refactor Tasks
+
+Convert findings into task units with:
+
+- problem
+- evidence
+- impact
+- effort
+- priority
+- related pages
+- related MCP
+- Codex implementation prompt
+- verification method
+- risks
+
+Tasks should be scoped enough for Codex to run in the target website repo after repo intake. Avoid tasks that mix unrelated design, copy, and technical work unless they are one user-flow fix.
+
+### 5. Generate Prompts
+
+Generate the appropriate prompt:
+
+- Codex repo intake
+- Codex implementation
+- Codex visual QA
+- Codex deployment verification
+- Claude design review
+- Claude competitor research
+- Claude copy/UX critique
+- final handoff report
+
+Every Codex prompt must say that the work happens in the target website repo and must preserve the target repo's architecture, components, state patterns, styling conventions, and verification commands.
+
+### 6. Produce Handoff Report
+
+The report should include target site information, diagnostic summary, major issues, priority recommendations, executed work, verification results, remaining risks, and next tasks.
+
+## Output Template
+
+Use [`TEMPLATE.md`](TEMPLATE.md) for the final report or planning artifact.
+
+## Verification phase
+
+- [ ] Site Profile includes live URL, target repo reference, pages, user flows, viewports, and platform notes.
+- [ ] Audit categories cover visual, UX, responsive, accessibility, performance, SEO, technical, runtime, and content quality.
+- [ ] MCP readiness uses only `required`, `optional`, `unused`, or `unavailable`.
+- [ ] Refactor tasks include problem, evidence, impact, effort, priority, pages, MCP, prompt, verification, and risks.
+- [ ] Codex prompts clearly state that implementation happens in the target website repo.
+- [ ] Handoff report includes verification evidence or explicit placeholders for evidence not yet run.
+- [ ] Accessibility, responsive, and source-grounding notes are present.
+
+## Done when
+
+- One Website Improvement plan or handoff report is produced.
+- The plan can be executed by Codex in the target repo without requiring design-ai to contain the target source.
+- The MVP boundary is explicit: no automatic crawling, external writes, model training, embeddings, or target repo mutation from design-ai.

package/skills/website-improvement/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: website-improvement
+description: Plan and coordinate professional website improvement work. Use for existing website audits, Site Profile setup, MCP readiness planning, refactor task generation, Codex/Claude prompt generation, and handoff reports.
+---
+
+See [PLAYBOOK.md](PLAYBOOK.md).

package/skills/website-improvement/TEMPLATE.md

@@ -0,0 +1,103 @@
+# Website Improvement Plan: <site name>
+
+> Live URL: <url>
+> Target repo: <repo URL or local path>
+> Viewports: desktop / tablet / mobile
+> Status: planning / implementation / verification / handoff
+
+## Site Profile
+
+- Name:
+- Live URL:
+- Repo URL:
+- Local path:
+- Figma URL:
+- Deploy provider:
+- Sentry project:
+- CMS:
+- Database:
+- Priority pages:
+- Primary user flows:
+- Brand/design notes:
+
+## Audit Summary
+
+| Category | Status | Key findings |
+| --- | --- | --- |
+| Visual Design | todo |  |
+| UX Flow | todo |  |
+| Responsive QA | todo |  |
+| Accessibility | todo |  |
+| Performance | todo |  |
+| SEO | todo |  |
+| Technical Quality | todo |  |
+| Runtime Issues | todo |  |
+| Content Quality | todo |  |
+
+## MCP Readiness
+
+| MCP | Status | Reason |
+| --- | --- | --- |
+| GitHub | required |  |
+| Figma | optional |  |
+| Browser/Playwright | required |  |
+| Chrome DevTools | optional |  |
+| Deploy | required |  |
+| Sentry | optional |  |
+| Database | unused |  |
+| CMS | optional |  |
+| Collaboration | optional |  |
+| Research | optional |  |
+
+## Refactor Plan
+
+### [P1] <task title>
+
+- Category:
+- Problem:
+- Evidence:
+- Impact:
+- Effort:
+- Pages:
+- Recommended MCP:
+- Codex prompt:
+- Verification:
+- Risks:
+
+## Prompt Pack
+
+### Codex repo intake
+
+```text
+<prompt>
+```
+
+### Codex implementation
+
+```text
+<prompt>
+```
+
+### Claude design review
+
+```text
+<prompt>
+```
+
+## Handoff Report Draft
+
+### Executed Work
+
+- Not run yet.
+
+### Verification Results
+
+- Not run yet.
+
+### Remaining Risks
+
+- Not run yet.
+
+### Next Actions
+
+- Not run yet.

package/tools/audit/changelog-generate.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""
+Generate CHANGELOG.md from git commit history.
+
+Reads commits since the last tag (or all commits if no tags) and
+formats them into a markdown changelog grouped by version.
+
+Usage:
+  python3 tools/audit/changelog-generate.py [--since vN] [--output CHANGELOG.md]
+
+Categorizes commits by conventional-commit prefix:
+  feat: → "Added"
+  fix: → "Fixed"
+  refactor: → "Changed"
+  docs: → "Documentation"
+  chore: → "Maintenance"
+  perf: → "Performance"
+
+Skips commits matching ^(chore: bump|chore: release).
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from datetime import date
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+CATEGORY_MAP = {
+    "feat": "Added",
+    "fix": "Fixed",
+    "refactor": "Changed",
+    "docs": "Documentation",
+    "chore": "Maintenance",
+    "perf": "Performance",
+    "test": "Testing",
+    "ci": "CI/CD",
+    "build": "Build",
+    "style": "Style",
+    "revert": "Reverted",
+}
+
+SKIP_PATTERNS = [
+    r"^chore:\s*bump",
+    r"^chore:\s*release",
+    r"^Merge\s+",
+]
+
+
+def run(cmd: list[str]) -> str:
+    return subprocess.run(cmd, capture_output=True, text=True, cwd=ROOT, check=True).stdout
+
+
+def get_tags() -> list[str]:
+    out = run(["git", "tag", "--sort=-creatordate"])
+    return [t.strip() for t in out.splitlines() if t.strip()]
+
+
+def get_commits_between(start: str | None, end: str = "HEAD") -> list[tuple[str, str, str]]:
+    """Return (sha, subject, date) tuples."""
+    if start:
+        rev_range = f"{start}..{end}"
+    else:
+        rev_range = end
+    out = run(["git", "log", "--pretty=format:%h|%s|%ad", "--date=short", rev_range])
+    commits = []
+    for line in out.splitlines():
+        if not line.strip():
+            continue
+        parts = line.split("|", 2)
+        if len(parts) == 3:
+            commits.append((parts[0], parts[1], parts[2]))
+    return commits
+
+
+def should_skip(subject: str) -> bool:
+    for pattern in SKIP_PATTERNS:
+        if re.match(pattern, subject):
+            return True
+    return False
+
+
+def categorize(subject: str) -> str:
+    match = re.match(r"^(\w+)(?:\(([^)]+)\))?:\s*(.+)$", subject)
+    if not match:
+        return "Other"
+    prefix = match.group(1).lower()
+    return CATEGORY_MAP.get(prefix, "Other")
+
+
+def strip_prefix(subject: str) -> str:
+    """Remove the conventional-commit prefix from the subject for cleaner display."""
+    match = re.match(r"^(\w+)(?:\(([^)]+)\))?:\s*(.+)$", subject)
+    if match:
+        return match.group(3)
+    return subject
+
+
+def render_section(version: str, commit_date: str, commits: list[tuple[str, str, str]]) -> str:
+    """Render one version section."""
+    if not commits:
+        return ""
+
+    by_category: dict[str, list[tuple[str, str]]] = {}
+    for sha, subject, _ in commits:
+        if should_skip(subject):
+            continue
+        cat = categorize(subject)
+        by_category.setdefault(cat, []).append((sha, strip_prefix(subject)))
+
+    if not by_category:
+        return ""
+
+    out = [f"## [{version}] — {commit_date}\n"]
+    # Order categories logically
+    order = ["Added", "Changed", "Fixed", "Removed", "Performance", "Documentation", "Testing", "CI/CD", "Build", "Maintenance", "Style", "Reverted", "Other"]
+    for cat in order:
+        if cat not in by_category:
+            continue
+        out.append(f"### {cat}\n")
+        for sha, subject in by_category[cat]:
+            out.append(f"- {subject} ({sha})")
+        out.append("")
+    return "\n".join(out)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--since", help="Generate from this version backwards")
+    parser.add_argument("--output", default="CHANGELOG.md", help="Output file (default: CHANGELOG.md)")
+    parser.add_argument("--unreleased-version", default="Unreleased", help="Label for unreleased commits")
+    args = parser.parse_args()
+
+    output_path = ROOT / args.output
+
+    sections = [f"# Changelog\n\n_Generated by `tools/audit/changelog-generate.py` on {date.today().isoformat()}._\n"]
+
+    tags = get_tags()
+    if not tags:
+        # No tags — all commits as "Unreleased"
+        commits = get_commits_between(None)
+        sections.append(render_section(args.unreleased_version, date.today().isoformat(), commits))
+    else:
+        # Unreleased = HEAD .. latest tag
+        unreleased = get_commits_between(tags[0], "HEAD")
+        if unreleased:
+            sections.append(render_section(args.unreleased_version, date.today().isoformat(), unreleased))
+
+        # Each tag-to-tag range
+        for i, tag in enumerate(tags):
+            prev_tag = tags[i + 1] if i + 1 < len(tags) else None
+            commits = get_commits_between(prev_tag, tag)
+            tag_date_out = run(["git", "log", "-1", "--pretty=format:%ad", "--date=short", tag]).strip()
+            section = render_section(tag, tag_date_out, commits)
+            if section:
+                sections.append(section)
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text("\n".join(s for s in sections if s) + "\n", encoding="utf-8")
+    try:
+        display_path = output_path.relative_to(ROOT)
+    except ValueError:
+        display_path = output_path
+    print(f"Wrote {display_path}")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except subprocess.CalledProcessError as e:
+        print(f"git command failed: {e.stderr}", file=sys.stderr)
+        sys.exit(1)