Prepare Local Agent Input Before AI UI Generation

Quick Start

1. Compile the bundle. Generate a deterministic bundle for the target surface under artifacts/generation-bundles.
2. Prepare one surface payload. Resolve the bundle into one agent-ready JSON document under artifacts/generation-inputs.
3. Feed the prepared payload into the agent. Use the prepared JSON for bundle-aware generation instead of loading the raw contract directly.
4. Generate in the repo. Let the agent edit code inside the workspace while staying inside the surface-owned boundary.
5. Validate against the same bundle. Run workspace mode validation after generation and treat block as a stop condition.
6. Repeat until pass or accepted warn. Feed structured findings back into the next generation attempt.
7. Use tracked sessions when you need iteration evidence. init-generation-session, record-generation-attempt, and summarize-generation-session freeze inputs, record each validate result, and aggregate recurring issues.

Copy/Paste Start

# 1) Compile the contract into a generation bundle
node scripts/interfacectl-tool.mjs run cli compile \
  --contract /Users/mike/SurfacesPlatform/surfaces-webapps/contracts/surfaces.web.contract.json \
  --out /Users/mike/SurfacesPlatform/surfaces-webapps/artifacts/generation-bundles/surfaces-web

# 2) Resolve one surface into an agent-ready payload
node scripts/interfacectl-tool.mjs run cli prepare-generation \
  --bundle-root /Users/mike/SurfacesPlatform/surfaces-webapps/artifacts/generation-bundles/surfaces-web \
  --surface surfaces-web \
  --out /Users/mike/SurfacesPlatform/surfaces-webapps/artifacts/generation-inputs/surfaces-web.json

# 3) Generate or edit UI, then validate against the same bundle
node scripts/interfacectl-tool.mjs run cli validate-generation \
  --tool codex \
  --surface surfaces-web \
  --mode workspace \
  --workspace-root /Users/mike/SurfacesPlatform/surfaces-webapps \
  --bundle-root /Users/mike/SurfacesPlatform/surfaces-webapps/artifacts/generation-bundles/surfaces-web

# Optional: freeze one proof-loop session with attempt tracking
node scripts/interfacectl-tool.mjs run cli init-generation-session \
  --bundle-root /Users/mike/SurfacesPlatform/surfaces-webapps/artifacts/generation-bundles/surfaces-web \
  --surface surfaces-web \
  --workspace-root /Users/mike/SurfacesPlatform/surfaces-webapps \
  --tool codex \
  --session codex-surfaces-web
node scripts/interfacectl-tool.mjs run cli record-generation-attempt \
  --session-dir /Users/mike/SurfacesPlatform/surfaces-webapps/artifacts/generation-sessions/surfaces-web/codex-surfaces-web \
  --assessment-file /Users/mike/SurfacesPlatform/surfaces-webapps/artifacts/generation-sessions/surfaces-web/codex-surfaces-web/assessment.json
node scripts/interfacectl-tool.mjs run cli summarize-generation-session \
  --session-dir /Users/mike/SurfacesPlatform/surfaces-webapps/artifacts/generation-sessions/surfaces-web/codex-surfaces-web

• prepare-generation is the local-agent handoff and keeps bundle semantics centralized in interfacectl.
• Generation session commands are canonical interfacectl workflow, not repo-local wrappers.
• Workspace mode validation remains the authoritative gate after code is written.
• Hosted builders still stay on the descriptor + HTTP adapter path.
• The prepared payload is tool-neutral and can be wrapped in Codex, Cursor, or Claude Code workflows.
• Keep the compiled bundle and prepared JSON in artifacts/ so the same inputs can be reused across iterations.

Status Rules