frontend-handoff-builder

English | 中文

Turn raw frontend input into a stronger handoff package before code generation.

This project is an input-enhancement skill for frontend generation. It sits between the user's raw brief and a downstream coding agent such as Claude, Codex, or OpenClaw.

raw input -> optimized handoff -> downstream agent -> better frontend result

What it does

Instead of sending a thin prompt straight to a coding agent, this skill first:

1. locks key task decisions with intake questions
2. normalizes the request into a structured profile
3. supplements missing materials
4. assembles a handoff package
5. verifies the package before implementation

The current public-quality route is text -> single-page website.

Visual comparison

Text-only input can already produce a visibly better result once the page gets:

• real local image assets
• local SVG icons and marks
• explicit image crop and framing guidance
• clearer section mapping and non-negotiables

Baseline: raw prompt directly to coding agent	With handoff package

See the full worked example in examples/text-only-single-page.

Example input

Source prompt: examples/text-only-single-page/raw-prompt.md

Build a single-page website for Northline Lodge, a premium winter retreat for remote teams in the Alps.

The site should feel cinematic, calm, and premium, but still practical enough for people who want to understand whether they can actually work there for a week.

Please include:
- a hero section
- retreat highlights
- stay options
- a sample day rhythm
- workspaces and connectivity
- fireside evening section
- FAQ
- booking CTA

Use real imagery instead of placeholders if possible. Avoid fake testimonials, fake awards, or vague luxury language.

What the skill adds on the text-first route

For text-only single-page work, the current enhancement methods are:

1. intake clarification before material collection
2. real image search and local asset download
3. local SVG generation for logo, icons, arrows, and simple graphics
4. image presentation metadata such as fit_mode, recommended_aspect_ratio, focal_point, and crop_notes
5. a verifier that checks package consistency before downstream implementation

All final images must be stored locally inside the package. Remote URLs are allowed as discovery or provenance, but not as final asset paths.

How to use

For the current stable route:

1. start from a raw text brief
2. answer three mandatory intake questions
3. supplement materials
4. build the handoff package
5. run verification
6. pass the verified package to a downstream coding agent

The three mandatory intake questions are:

1. page use
2. style direction
3. output architecture

Allowed output architectures:

• single_html
• react_vite_repo
• vue_vite_repo

Output package

Preflight artifacts:

• intake-questions.md
• intake-answers.json
• normalized-brief.md

Handoff package:

• input-profile.json
• collection-plan.md
• content-plan.json
• style-tokens.json
• asset-manifest.json
• generation-spec.md
• agent-handoff.md
• verification-report.md

The main downstream brief is agent-handoff.md, with this fixed section order:

1. Goal
2. Output target
3. Scenario
4. Inputs and references
5. Non-negotiables
6. Content mapping
7. Asset usage rules
8. Recommended implementation path
9. Agent-specific notes

Example files

• raw prompt: examples/text-only-single-page/raw-prompt.md
• intake answers: examples/text-only-single-page/intake-answers.json
• normalized brief: examples/text-only-single-page/normalized-brief.md
• analysis: examples/text-only-single-page/analysis.md
• baseline page: examples/text-only-single-page/baseline/index.html
• handoff page: examples/text-only-single-page/with_skill/index.html
• handoff manifest: examples/text-only-single-page/with_skill/asset-manifest.json
• verification report: examples/text-only-single-page/with_skill/verification-report.md

Scripts

Create intake artifacts:

uv run python scripts/build_intake.py \
  --project-name northline-lodge-retreat \
  --raw-brief examples/text-only-single-page/raw-prompt.md \
  --page-use marketing_landing_page \
  --style-direction premium_cinematic \
  --output-target single_html \
  --required-sections hero,highlights,stay-options,day-rhythm,workspaces,fireside,faq,cta \
  --must-include "real imagery if possible,practical remote-team framing" \
  --must-avoid "fake testimonials,fake awards,vague luxury filler" \
  --follow-up "Should the page prioritize conversion or a slower editorial mood?" \
  --output-dir /tmp/northline-intake

Build the handoff package:

uv run python scripts/build_handoff.py \
  --project-name northline-lodge-retreat \
  --input-profile path/to/input-profile.json \
  --collection-plan path/to/collection-plan.md \
  --content-plan path/to/content-plan.json \
  --style-tokens path/to/style-tokens.json \
  --asset-manifest path/to/asset-manifest.json \
  --intake-answers path/to/intake-answers.json \
  --output-dir /tmp/northline-handoff

Verify the package:

uv run python scripts/verify_handoff.py \
  --package-dir /tmp/northline-handoff \
  --intake-answers path/to/intake-answers.json

Status

Stable

• text-only single-page route
• mandatory intake before material collection
• real image supplementation with local asset storage
• local SVG supplementation
• image framing metadata in the handoff
• package verification before downstream implementation

In progress

• screenshot-led route
• URL-led route
• PDF / PRD / markdown document route
• more public examples
• broader cross-agent evaluation

More docs

• skill instructions: SKILL.md
• Chinese docs: README.zh.md
• schemas: references/schemas.md
• generation guidance: references/code-generation.md

License

MIT