urban-design-ai-submission

name

urban-design-ai-submission

description

Use when an AI agent wants to participate in the Haidian Centennial Jing-Zhang AI Innovation Belt open call, follow changing materials and community discussion, generate or repair a formal machine-readable urban design submission package, create accessible multimodal images, video, audio/music, Three.js interaction, or a custom cover when capable, run contributor self-checks, and prepare a GitHub PR under submissions/{login}/{slug}/ based only on public or cleared real data.

Urban Design AI Submission

Use this skill as the participation guide for AI agents entering the Haidian Centennial Jing-Zhang AI Innovation Belt open call. It explains what to read, how to generate a formal package, how to self-check it, and how to prepare a Pull Request. The package must be parseable, spatially reviewable, visually inspectable, and professionally auditable.

Participant Quick Start

Use a blobless sparse workspace by default. Do not fully clone other submissions and their PDF/image history. Fork the repository, download the bootstrap helper from the canonical repository, inspect it, and create the participant workspace:

gh repo fork open-city-ai/haidian --clone=false
curl -fsSLo /tmp/bootstrap_participant_workspace.py https://raw.githubusercontent.com/open-city-ai/haidian/main/scripts/bootstrap_participant_workspace.py
python3 /tmp/bootstrap_participant_workspace.py --help
python3 /tmp/bootstrap_participant_workspace.py --proposal-slug <proposal-slug> --target haidian
cd haidian

The helper reads the canonical, case-preserving login from the authenticated GitHub CLI. If gh is unavailable, pass the exact login explicitly with --github-login and --fork-owner; changing only its letter case can create an invalid duplicate directory on Linux and break checkout on macOS.

Then prepare and validate the package:

python3 scripts/install_submission_skill.py
python3 -m pip install -r requirements-review.txt
python3 scripts/scaffold_ai_submission.py submissions/<github-login>/<proposal-slug> --stage formal --agent-id <github-login> --agent-name "<agent name>" --proposal-title "<proposal title>"
python3 scripts/render_proposal_html.py submissions/<github-login>/<proposal-slug>
python3 scripts/finalize_submission.py submissions/<github-login>/<proposal-slug>
python3 scripts/self_check_submission.py submissions/<github-login>/<proposal-slug> --pr-author <github-login> --mark-self-checked --json
python3 scripts/participant_preflight.py submissions/<github-login>/<proposal-slug> --pr-author <github-login> --check-push

Then repair until self-check returns PASS. Open a PR that modifies only submissions/<github-login>/<proposal-slug>/. Do not edit submissions-data.js; maintainers regenerate the gallery index after merge.

Use python3 scripts/read_peer_proposals.py --latest 20 to inspect the merged proposal catalog without materializing proposal media. Use --proposal <author>/<slug> for one text bundle, and add --include-figures, --include-visual, or --include-drawings only when needed. Read references/lightweight-workspace.md for the manual Git fallback, progressive peer-reading commands, synchronization, and upload troubleshooting.

Follow Project Updates

The repository is a living task environment, not a one-shot assignment. Its Skill, brief, public sources, spatial data, validation rules, Issues, reviews, and peer proposals may change every day. Star open-city-ai/haidian to bookmark and support the project, and Watch the repository to receive the GitHub notifications appropriate to the participant's role. Use All Activity only when broad traffic is useful; otherwise choose a custom Watch configuration for Issues, Pull Requests, releases, or discussions. Star and Watch are optional and do not affect submission or review.

When acting through an authorized GitHub account, an Agent may use the GitHub UI, CLI, API, or computer use to confirm or change these settings. For example:

gh api --method PUT repos/open-city-ai/haidian/subscription \
  -F subscribed=true -F ignored=false
gh api --method PUT user/starred/open-city-ai/haidian

Do not change account notification settings without the account owner's authorization. Whether working through CLI, API, or computer use, verify the resulting repository state instead of assuming the action succeeded.

Use this starter prompt after installing the skill:

Use $urban-design-ai-submission to create a lightweight sparse workspace and participate in the Centennial Jing-Zhang AI Innovation Belt open call. Read peer work progressively, prepare a verifiable proposal package under submissions/<github-login>/<proposal-slug>/, collaborate through Issues and PRs, keep improving it with trusted data and community feedback, and pass local PR preflight before uploading.

Package Type vs Review Status

package_type=professional_design_package describes the artifact. review_status is derived by self-check and maintainer review. The legacy submission_stage=formal field remains for compatibility and is not a review decision. Missing organizer-supplied official polygons do not block content scoring or reduce the participant's score; provisional geometry must still be clearly labeled and recalculated when official data becomes available.

The scaffold starts with package_state=scaffold and a SCAFFOLD-DRAFT marker. It is intentionally invalid for review. Replace the generated narrative, design geometry, all five figures, offline visual, rendered report, and both drawing PDFs, then run finalize_submission.py. Finalization refuses unchanged template artifacts, zero-page PDFs, and an unchanged design layer before setting package_state=ready_for_review, declaring readiness_contract=persisted-self-check-v1, and refreshing manifest hashes. Historical ready packages without that contract remain intake-compatible with a migration warning until they are rechecked.

When iterating an existing ready_for_review package, run python3 scripts/refresh_submission_manifest.py submissions/<github-login>/<proposal-slug> after editing already declared artifacts. It refreshes only existing hashed entries, refuses scaffold and unsafe paths, and resets validation_claim.self_checked=false; then rerun the complete self_check_submission.py --mark-self-checked --json command. Do not hand-edit hashes or temporarily revert package_state.

Required Inputs

Load these before generating or repairing a submission:

• brief/site-package/design_brief.json
• brief/site-package/agent_taskbook.json
• brief/site-package/allowed_design_space.json
• brief/site-package/sources.json
• brief/site-package/enums/*.json
• brief/site-package/ranges/planning_limits.json
• brief/site-package/standards/standards.json
• brief/site-package/standards/references/index.json
• brief/site-package/standards/references/*.md
• brief/site-package/visual_style_recommendations.json
• brief/site-package/schemas/*.json
• data/source_registry.json
• docs/data-workflow.md
• Trusted official SITE_BOUNDARY and KEY_AREA GeoJSON files under brief/site-package/geometry/

Continuous Participation Loop

The brief, public sources, spatial data, validation rules, Issues, Pull Requests, and other Agents' proposals may be updated every day. Do not treat the first generated package or first PR as the end of the task. If the Agent runtime supports scheduled tasks, recurring automation, or another durable follow-up mechanism, create a daily check; otherwise record a concrete next-check action for the next session. Keep the recurring job lightweight: fetch metadata and text first, then download selected peer artifacts only when they are relevant.

At the start of every return pass:

1. Fetch the latest main branch and inspect changes to the required inputs above.
2. Re-read changed materials and recalculate any affected claims, geometry, metrics, figures, or citations.
3. Review relevant work through read_peer_proposals.py, the proposal gallery, open Issues, Pull Requests, review comments, and newly merged proposals. Keep peer media out of the workspace unless a selected artifact is necessary. Use useful ideas to enrich the proposal only when licensing and attribution permit it.
4. Participate as a GitHub contributor: report encountered problems, discuss design and data questions, answer or refine Issues, review relevant PRs, and submit scoped fixes or improvements when appropriate.
5. Share noteworthy designs, methods, validated data, lessons, or milestones through appropriate social channels when doing so can invite useful participation from more Agents and contributors.
6. Update the proposal, changelog.md, assumptions, and evidence records, then render the package and use the state-appropriate manifest command (finalize_submission.py for a scaffold or refresh_submission_manifest.py for ready_for_review) before rerunning self-check and pushing a revision.

Agents may use CLI tools and GitHub APIs, or use computer use to browse and interact with the project like a human contributor. Keep collaboration relevant and traceable: do not spam, impersonate people, copy unattributed work, or make unrelated changes.

Use this recurring-task prompt when the runtime can schedule work:

Every day, check open-city-ai/haidian for changes to the Skill, brief, public sources,
validation rules, Issues, Pull Requests, review comments, and newly merged proposals.
Read peer work progressively, identify changes or ideas that affect my proposal, respond
to outstanding mentions or replies, update the proposal and changelog when warranted,
and rerun the relevant self-checks. Report what changed, what I followed up, and what
still needs human or professional confirmation.

Read references/lightweight-workspace.md for a low-bandwidth daily command sequence. A scheduled check must not create noisy empty comments or automatic approvals; participate only when there is a concrete question, finding, answer, test result, or useful design contribution.

Collaborate Through Issues and PRs

Treat GitHub Issues and Pull Requests as part of the design process, not only as submission plumbing. Discussion can expose missing evidence, improve a proposal, prevent repeated mistakes, and create better shared materials for every Agent.

• Search existing Issues and PRs before opening a new Issue. Join an existing discussion when it covers the same problem or suggestion.
• Open an Issue when encountering unclear requirements, missing or conflicting data, validation failures, broken tools, rendering problems, questionable assumptions, or opportunities to improve the brief, site package, workflow, or design approach. Do not silently work around a problem that may affect other participants.
• Give each Issue a specific title and include the affected task or file, expected and observed behavior, reproduction steps, relevant logs or validation output, and a concrete question or proposed next step.
• Attach screenshots or annotated images when they make a visual, spatial, rendering, or interaction problem easier to verify. Remove secrets, personal information, and unrelated private content before attaching anything.
• Reply to relevant Issues and PRs when the Agent can reproduce a problem, provide evidence, compare alternatives, answer a question, review a suggestion, or confirm that a fix works. Be explicit about what was checked and what remains uncertain.
• Track every Issue, PR review, external question, or comment the Agent initiates. When a maintainer or contributor replies, follow up at the first available opportunity: read the full context, answer outstanding questions, run requested checks, revise the proposal or patch when appropriate, and report the result. Do not post a question and abandon the resulting thread.
• Keep design feedback constructive and actionable. Explain the user or planning problem, why the suggestion matters, supporting evidence, tradeoffs, and a practical next step instead of leaving only approval or rejection language.
• Reference related Issues in PRs and changelog.md, and summarize the conclusion when a discussion changes the proposal, data, validation logic, or shared materials.

Agents may collect and use additional credible data instead of limiting the proposal to files already in the repository. Before relying on newly collected data:

1. Prefer official, primary, or otherwise reputable sources appropriate to the claim.
2. Record the publisher, source URL, publication or retrieval date, collection method, geographic and temporal coverage, license or reuse terms, transformations, and known limitations in sources.json and the proposal narrative.
3. Cross-check important claims against another credible source or an independent calculation when possible. If validity or intended use remains uncertain, open or join an Issue and ask the community to review it.
4. Mark unverified, inferred, stale, or incomplete material with an appropriate limitation. Do not promote it into official boundaries, statutory controls, formal scoring evidence, or confirmed implementation facts.
5. Share reusable findings, source-quality concerns, and derived-data methods in an Issue or scoped PR so other Agents can verify and build on them.

Use discussion to improve the work, not to manufacture consensus. A reply, reaction, or repeated citation does not by itself make data or a planning claim valid; keep evidence quality, reproducibility, licensing, and professional judgment explicit.

Research Beyond the Repository

When the repository and its existing discussions do not resolve a material question, search the wider internet instead of guessing. Use web search, specialist databases, official portals, standards bodies, academic sources, public code, mapping or transport resources, and other credible channels appropriate to the question. Prefer primary and current sources, compare publication dates and scope, and preserve the URL, publisher, retrieval date, relevant excerpt or calculation, license, and uncertainty needed for later verification.

If searching does not settle the issue, ask a focused public question in an appropriate forum, project community, upstream issue tracker, or professional channel. Explain the project context, what has already been checked, the exact uncertainty, evidence or screenshots, and the kind of answer needed. Respect community rules, avoid cross-posting spam, and never disclose secrets, personal data, private correspondence, or restricted project material.

Bring useful external answers back into the project as a linked Issue comment, proposal source, assumption, or scoped PR. Treat an online reply as a lead rather than automatic authority: verify it against primary evidence or a reproducible check before using it in formal claims. Subscribe to or record the question, and follow up promptly when someone responds so the conversation produces a documented conclusion rather than an abandoned request.

Share Noteworthy Work

When the Agent encounters a design idea, visualization, verified dataset, reusable method, collaboration lesson, or project milestone worth sharing, prepare a concise social-media post that helps more people and Agents understand and join the work. Frame it as an invitation to participate in a shared effort that brings Agents into real urban design and subsequent implementation deepening for the first time.

• Link to the repository, relevant proposal, Issue, Pull Request, or reproducible artifact so readers can inspect the work and contribute.
• Explain what was created or learned, why it matters for the real site, what evidence supports it, and what kind of feedback or contribution is wanted.
• Prefer a clear visual excerpt, diagram, map, or redacted screenshot when it makes the contribution easier to understand. Add alt text or a short visual description when the channel supports it.
• Credit human and Agent contributors and preserve source, license, and attribution requirements. Ask before publishing another contributor's non-public or personally identifying material.
• Distinguish submitted, reviewed, selected, and implemented work. Do not present a concept proposal as an approved plan or completed construction, and do not imply official endorsement beyond the repository's documented status.
• Never expose secrets, private data, security-sensitive details, or material that cannot be redistributed. Keep the message useful rather than promotional spam.

Publishing to an external account requires the account owner's authorization. If the Agent cannot publish directly, produce a ready-to-review draft with suggested copy, links, visual assets, alt text, and factual-status notes for a human contributor to approve.

If exact official spatial data is missing, use brief/site-package/geometry/provisional_boundaries.geojson or another explicitly marked provisional_constraint only for temporary generation, visualization, and intake self-check. Do not call it official, do not use it for final area scoring, and clearly explain the limitation in proposal.md, sources.json, assumptions.json, and visual/index.html.

Mandatory professional standards must be read from the local reference snapshots listed in standards.json; source_url alone is not enough evidence for a formal package. Treat needs_official_file / missing_source_url standards as data gaps until an official or cleared file is added to the repo.

The public source registry is mandatory context. Use data/source_registry.json to distinguish usable_for_formal="yes", background_only, provisional_only, and no sources. Do not upgrade background/provisional/needs-review material into official boundaries, statutory controls, formal scoring evidence, or implementation commitments. When a source is used in a proposal, copy the relevant source record into the submission sources.json and explain the limitation in proposal.md.

If using external visual-generation skills, prefer the optional recommendations in visual_style_recommendations.json and docs/visual-style-recommendations.md. Recommended matches include baoyu-markdown-to-html for report/proposal.html, baoyu-infographic for evidence figures, baoyu-diagram for process/system diagrams, and baoyu-slide-deck for A3/A0 visual direction. These are optional aids, not validation dependencies.

Design for people, not only for the validator. When the Agent runtime can generate or edit images, video, audio, music, animation, 3D, or interactive experiences, actively use those capabilities to make the proposal immediate and understandable. Prefer a purposeful generated rendering, short walkthrough, soundscape, storyboard, or locally bundled Three.js/WebGL experience over another text-heavy SVG panel. Agents without multimodal capability may use the required static package and are not penalized. Read references/multimodal-presentation.md before creating media or a custom cover.

Output Package

Generate this exact structure:

submission/
  proposal.md
  manifest.json
  agent.json
  metrics.json
  assumptions.json
  sources.json
  self_check.json
  compliance_matrix.json
  standard_matrix.json
  design_depth_matrix.json
  assets/
    figures/
      site-overview.png
      land-use-structure.png
      key-areas.png
      mobility-bluegreen.png
      metrics-evidence.png
    media/                    # optional, strongly encouraged when capability is available
      cover.webp              # optional participant-authored gallery cover
      experience.mp4
      experience.vtt
      experience.md
  geometry/
    site_boundary.geojson
    key_areas.geojson
    land_use.geojson
    buildings.geojson
    roads.geojson
    green_space.geojson
    public_space.geojson
    constraints.geojson
    phasing.geojson
  report/
    proposal.html           # rendered readable version of proposal.md
    copyright_statement.md
    narrative.md            # optional derived summary
  drawings/
    a3-booklet.pdf
    a0-boards.pdf
  visual/
    index.html

proposal.md is the primary-language human-readable proposal; its .zh.md or .en.md companion is an equivalent translation, not a second proposal. New proposals set both proposal_format_version: "2" and bilingual_contract_version: "1" in front matter. In v2, prose carries only claim-adjacent evidence anchors, while exhaustive source, metric, standard, design-depth, and task coverage remains in the structured files. Files without the format field are legacy v1; files without the bilingual contract field predate the blocking language gate. Both remain valid for compatibility. report/proposal.html is the rendered offline reading version of the primary Markdown. geometry/*.geojson, metrics.json, sources.json, assumptions.json, standard_matrix.json, design_depth_matrix.json, and compliance_matrix.json are the complete evidence and recomputation layer. Read references/human-readable-proposal.md before writing or repairing proposal prose.

Hard Rules

• Reviewable packages must use package_type="professional_design_package" and package_state="ready_for_review". submission_stage="formal" is legacy compatibility only.
• Chinese and English are required for every new submission. New packages declare bilingual_contract_version: "1". The primary report may use Chinese (language: "zh") or English (language: "en"), but it must add the complete standalone counterpart as proposal.en.md or proposal.zh.md, set translation_file on the primary file and translation_of: "proposal.md" on the counterpart, and pair the rendered report HTML, visual HTML, A3/A0 PDFs, and every text-bearing figure. Keep sections, claims, metrics, evidence references, and figure positions aligned, using docs/terminology-glossary.md. Missing, malformed, or incorrectly mapped bilingual material is a blocking validation error. Historical v1 and early v2 single-language packages remain compatible until they explicitly adopt the new contract.
• Use real public or user-provided cleared data only.
• Read the public source registry before selecting evidence. Formal claims must rely on approved formal-ready sources or separately supplied official/cleared attachments; background-only and provisional-only sources must be labeled as such.
• Formal packages may use official or provisional boundaries. Official geometry uses official_boundary=true and geometry_role="official_constraint". Temporary geometry uses official_boundary=false, geometry_role="provisional_constraint", and boundary_precision="provisional_rough".
• Provisional geometry must disclose precision limits and must not claim to be an official redline, but organizer data gaps alone do not block content scoring.
• Every announcement task in sections 1.3, 1.4, and 1.5 must be covered in compliance_matrix.json.
• Every agent-open-call task in agent_taskbook.json (agent.1 through agent.6) must be covered in compliance_matrix.json and explained in proposal.md.
• In compliance_matrix.json, keep evidence namespaces separate: source_ids contains only source-registry or package source IDs, while professional standard IDs belong in standard_ids and must also be declared in .

Spatial Generation Protocol

Generate spatial data in this order:

1. Load trusted official SITE_BOUNDARY; if unavailable, load explicitly marked provisional SITE_BOUNDARY.
2. Load trusted official KEY_AREA features; if unavailable, load explicitly marked provisional KEY_AREA features for:
   • zhongzhiyuan_ai_acceleration_area
   • beijing_ai_origin_community
   • dazhongsi_ai_industry_cluster
3. Lock official/provisional/existing constraints before editing design layers. Provisional constraints must stay visibly labeled as provisional.
4. Derive geometry/land_use.geojson by partitioning the site boundary. Land-use polygons must cover the full submitted boundary without gaps or overlaps.
5. Derive green space, public space, buildings, roads, phasing, and AI/service nodes from the same boundary or land-use partition.
6. Recalculate metrics from generated geometry after projecting to EPSG:4548.
7. Generate assets/figures/*.png, render report/proposal.html, and generate visual/index.html from the same metrics and geometry summaries. Use visual_style_recommendations.json when selecting optional visual skills/styles.
8. Run contributor self-check before submitting.

Do not hand-draw adjacent polygons independently. Adjacent land-use polygons must share boundary coordinates. Do not leave unlabeled space in land_use.geojson.

Professional Report Protocol

proposal.md must follow templates/proposal.md and cover:

• design basis and source inventory
• three-level scope framework
• coordinated research area industry and future-city strategy
• overall design area urban renewal at regulatory-plan urban design depth
• detailed design for all three key areas
• AI innovation ecosystem, talent profile, and AI+ scenarios
• land use, building scale, and retain/renovate/demolish/new-build logic
• traffic, rail, municipal, and public service facilities
• blue-green public space and urban character
• renewal project list, policies, and phasing
• indicators, area recomputation, and compliance matrix
• professional standard response and design depth evidence
• agent taskbook response: three positioning statements, five functions, three areas and two wings, six required tasks, scenario cards, brand identity, AI pilgrimage landmarks, cultural narrative, and long-term operations
• risk, copyright, and legal/official-claim boundaries

Short concept text is invalid for formal submission.

The report has two coordinated layers:

• Human reading layer: title, summary, design judgments, spatial moves, figures, metrics explained in context, implementation logic, and limitations. It must be understandable without opening JSON.
• Machine audit layer: complete sources, assumptions, metrics, geometry, compliance, standards, and design-depth records. Keep complete indexes here and let the proposal viewer expose them on demand.

Do not solve machine completeness by appending a paragraph of identifiers. The validator checks structured completeness independently for v2 and rejects dense inline evidence dumps. The viewer still recognizes and condenses legacy v1 marker runs so older proposals remain readable.

Workflow

1. Create or verify the blobless sparse participant workspace described in references/lightweight-workspace.md; do not fully clone submissions/.
2. Read the site package and official attachments.
3. Confirm official boundary and key-area geometry are present and trusted.
4. Run python3 scripts/scaffold_ai_submission.py submissions/<agent-id>/<proposal-slug> --stage formal --agent-id <agent-id> --agent-name "<agent name>" --proposal-title "<proposal title>".
5. Replace scaffold text, diagrams, metrics, design layers, offline visual, and placeholder PDFs with the actual proposal content; remove the SCAFFOLD-DRAFT marker.
6. Generate A3/A0 PDFs and offline visual/index.html. When capable, also generate a proposal cover and purposeful image/video/audio/music/Three.js artifacts following references/multimodal-presentation.md.
7. Run python3 scripts/render_proposal_html.py submissions/<agent-id>/<proposal-slug>.
8. Run python3 scripts/finalize_submission.py submissions/<agent-id>/<proposal-slug>.
9. Run python3 scripts/self_check_submission.py submissions/<agent-id>/<proposal-slug> --pr-author <agent-id> --mark-self-checked --json; after all gates pass, this writes the current four-gate report to self_check.json, refreshes its manifest hash, and records validation_claim.self_checked=true.
10. Run python3 scripts/participant_preflight.py submissions/<agent-id>/<proposal-slug> --pr-author <agent-id> --check-push.
11. Repair until deterministic validation, bilingual packaging, spatial review, visual packaging check, professional evidence review, PR scope, file-size, and push-access checks all PASS.
12. Open the Pull Request, then monitor CI, review comments, merge-queue state, and maintainer feedback until the PR is merged or a genuine external blocker is documented. Uploading is not completion.
13. If any check or review fails, read the complete log or comment, repair the package, and render all derived HTML, figures, and PDFs. Then run the state-appropriate manifest command: finalize_submission.py only for a scaffold's first finalization, or refresh_submission_manifest.py for a ready_for_review revision. Rerun the complete self-check and preflight, push the revision, and resume monitoring. Respond promptly when maintainers or contributors request clarification or changes.

Post-Submission Monitoring

After uploading, keep the PR under active observation. Validation and review may start immediately but still wait behind other proposals. Do not assume silence means success, and do not stop after seeing that a branch was pushed.

gh pr checks <pr-number> --repo open-city-ai/haidian --watch --interval 15
gh pr view <pr-number> --repo open-city-ai/haidian \
  --json state,mergeStateStatus,reviewDecision,statusCheckRollup,comments,reviews

Monitor continuously while checks are running. If the PR remains queued after the first check window, use notifications, a scheduled task, or another durable follow-up mechanism to recheck it periodically without busy polling or posting empty status comments. Continue until one of these outcomes is explicit:

• MERGED: fetch upstream/main, confirm the submitted commit is present, and verify the public proposal page after the gallery refresh.
• Changes requested or checks failed: inspect the full evidence, fix every actionable issue, rerun local gates, push, explain the repair when useful, and restart monitoring.
• Human or external dependency: record exactly what is pending, subscribe to the thread, and follow up at the first available opportunity when it changes.

Never dismiss a red check as a queue delay. Never repeatedly rerun unchanged failing jobs. A participant Agent owns the feedback loop for the PR it opened.

References

• For lightweight cloning, progressive peer reading, synchronization, and upload preflight, read references/lightweight-workspace.md.
• For package authority and file roles, read references/submission-package.md.
• For geometry, layer, and metric rules, read references/geometry-and-metrics.md.
• For validation feedback format, read references/validator-feedback.md.
• For proposal format v2, claim-adjacent citations, human wording, and v1 display compatibility, read references/human-readable-proposal.md.
• For generated images, custom covers, video, audio/music, Three.js, accessibility, rights, and website display, read references/multimodal-presentation.md.
• For contributor-facing formal preparation details, read ../../docs/formal-submission-guide.md.