Skip to content
Closed
Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
44 commits
Select commit Hold shift + click to select a range
0c2271e
feat(starters): add create-prototype-from-production skill to minimal
PCoelho Oct 30, 2026
33e4cb4
fix(starters): harden create-prototype-from-production after App runs
PCoelho Oct 30, 2026
81a89c9
fix(starters): close ledger, asset-size and canvas gaps in create-pro…
PCoelho Nov 4, 2026
12f4123
docs(starters): clarify production prototype authoring
PCoelho Nov 4, 2026
8a5ebe4
fix(starters): reject nonlocal coverage routes
PCoelho Nov 5, 2026
4bfcfd9
fix(starters): scope unattended production prototype runs
PCoelho Nov 5, 2026
757f817
fix(starters): isolate captured data from active guidance
PCoelho Nov 9, 2026
2f5b3b4
chore: sync main for fresh CI
PCoelho Nov 9, 2026
6a19625
test(hub): settle lazy canvas initialization before review checks
PCoelho Nov 9, 2026
42aeeb3
fix(starters): harden production-copy workflow
PCoelho Nov 11, 2026
8e534e5
fix(starters): reject unsafe context roots
PCoelho Nov 11, 2026
20eb670
fix(starters): enforce production ledger boundaries
PCoelho Nov 11, 2026
cc28cdb
docs(starters): redact sensitive captured URLs
PCoelho Nov 11, 2026
6564819
test(hub): isolate selection checks from bridge polling
PCoelho Nov 11, 2026
1a19628
fix(starters): validate guidance roots and evidence notes
PCoelho Nov 12, 2026
47559cb
fix(starters): reject credential-bearing ledger URLs
PCoelho Nov 12, 2026
33149e3
fix(starters): reject obvious private reference targets
PCoelho Nov 12, 2026
c06184c
fix(starters): tighten static public address ranges
PCoelho Nov 12, 2026
0089afd
fix(starters): require verified capture safety controls
PCoelho Nov 12, 2026
95175ee
fix(starters): harden reference URL input
PCoelho Nov 12, 2026
7214360
test(starters): include prototype helpers in app checks
PCoelho Nov 12, 2026
096989f
test(hub): explain canvas test synchronization
PCoelho Nov 12, 2026
2c7d125
docs(starters): keep copied validation guidance standalone
PCoelho Nov 12, 2026
55ff915
fix(starters): guard signed URLs and path sessions
PCoelho Nov 12, 2026
99490f3
fix(starters): validate canonical credential URL positions
PCoelho Nov 12, 2026
4f4a550
fix(starters): detect nested recognizable URL tokens
PCoelho Nov 12, 2026
ab3bbed
fix(starters): validate canonical fragments and private aliases
PCoelho Nov 12, 2026
241dbd7
test(hub): preserve reply fixture timestamp ordering
PCoelho Nov 12, 2026
1b1d93c
fix(starters): validate nested route fragments
PCoelho Nov 12, 2026
a2954d2
fix(starters): close reference validation gaps
PCoelho Nov 12, 2026
c3d08cb
fix(starters): use native parsing for nested URLs
PCoelho Nov 12, 2026
eef3dff
test(starters): cover ledger validation boundaries
PCoelho Nov 12, 2026
7d3ed33
fix(starters): inspect repeatedly encoded URL values
PCoelho Nov 12, 2026
4a8626d
docs(starters): verify source entry after scaffolding
PCoelho Nov 12, 2026
77cc88f
refactor(starters): copy Minimal default context without a helper script
PCoelho Nov 13, 2026
a73f71b
fix(starters): restore runnable production prototype workflow
PCoelho Nov 13, 2026
5020640
docs: keep one command for production-prototyping helper tests
PCoelho Nov 13, 2026
6262203
refactor(starters): shrink the production-prototype URL checker
PCoelho Nov 13, 2026
320bdbb
feat(starters): add a bounded asset downloader for production prototypes
PCoelho Nov 13, 2026
990fc5a
fix(starters): tighten production-prototype ledger checks
PCoelho Nov 13, 2026
c7853af
test(starters): fail when production-prototype tests are missing
PCoelho Nov 13, 2026
e834e87
style(starters): format production-prototype scripts
PCoelho Nov 13, 2026
020ffe6
fix(starter): stop when the capture browser cannot start
PCoelho Nov 13, 2026
1e0dcb8
fix(starter): keep asset downloads within the run budget
PCoelho Nov 13, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/starter-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,7 @@ jobs:
with:
node-version: ${{ matrix.node }}
- run: node --test scripts/create-prototype-repo.test.mjs scripts/setup-replica-plugin.test.mjs scripts/select-ci-suites.test.mjs
- run: node --test starters/minimal/.agents/skills/create-prototype-from-production/scripts/check-ledger.node-test.mjs
test:
name: Starter checks${{ matrix.starter.id != 'minimal' && format(' ({0})', matrix.starter.id) || '' }}${{ matrix.node == 26 && ' (Node 26)' || '' }}
needs: catalog
Expand Down
2 changes: 1 addition & 1 deletion scripts/create-prototype-repo.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -847,7 +847,7 @@ test("the shared bundle has a complete context library and working local links",
})

for (const [source, extraSkills, activeContext] of [
["starters/minimal", 0, false],
["starters/minimal", 1, false],
["starters/coreai", 11, true],
]) {
test(`${source} composes with shared guidance without collisions or broken links`, t => {
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
---
name: create-prototype-from-production
description: 'Use when asked to copy, clone, replicate or recreate a live production website or web app as a Replica prototype from its URL, such as "create a prototype from https://example.com" or "replicate this site for a demo". Do not use for building a new design from a brief, or for changing an existing prototype.'
---

# Create prototype from production

Turn a public production URL into a standalone, connected prototype in this
repository: every first-level destination built or explicitly stubbed, with a
coverage ledger and an honest difference report.

**The prototype is a standalone Vite app.** Hub is optional. Use the Replica canvas when available; explicitly authorized unattended local runs have the [shared preflight's local-preview exception](../../../REPLICA.md#canvas-preflight).

## Intake and unattended runs

Resolve scope and permission from the original request and prior answers. An explicit request for an unattended local run authorizes the local work listed below, subject to any exclusions in that request. Headless execution, autopilot and silence do not grant permission.

In unattended execution, never call a blocking question tool. Use the stated defaults for routine choices and record them in the handoff. Defer any operation requiring permission not already granted, continue independent authorized work, and report the limitation instead of waiting for an answer.

For attended runs, ask only unanswered intake questions before opening the site, in one batch when supported:

1. **Coverage.** Default: every first-level destination, meaning every link in the home page, header (including opened menus), mobile menu and footer. Alternatives: named sections only, or full sitemap.
2. **Go-ahead** for this repository: install locked dependencies if missing, run the local preview, build the prototype, and make focused local commits. Fresh context follows the app's scoped rules below. No push or publish.

Everything else is a stated default, never a question: use the site's real public assets and copy for a private demo; preserve its language; disable real submissions; keep external sites as outbound links; stop at login, OTP and CAPTCHA walls; keep assets of 25 MiB or less at original size, and serve a copy under 25 MiB for larger ones unless the request explicitly chooses otherwise.

This workflow never signs in, submits real data, pushes, publishes, changes other repositories or performs destructive actions. Those require a separate task and explicit authorization.

When authorized, commit at the end of Capture and again at the end of Build. If a commit cannot be made, report the failure and preserve the work; do not claim it was committed.

## Phases

| Phase | Read | Exit condition |
| -------- | ----------------------------------- | ---------------------------------------------------------------------------------------------- |
| Discover | [discover](./workflows/discover.md) | Ledger lists every in-scope destination with a decision |
| Capture | [capture](./workflows/capture.md) | Each family has a representative capture; every built page has content |
| Build | [build](./workflows/build.md) | `node .agents/skills/create-prototype-from-production/scripts/check-ledger.mjs --final` passes |

Load each workflow when its phase starts. Report the current phase in every
progress update.

## Context is produced here, not a prerequisite

Capturing the public reference needs no approved product context. Follow the [app's context rules](../../../AGENTS.md#product-guidance): an explicitly authorized unattended local run may create fresh capture-derived context when neither active root exists.

Preserve existing context, including `.github/contexts/`; do not overwrite it or create a higher-priority root to shadow it. Keep new observations under `reference/` and use existing guidance for Build. Required changes to existing guidance remain drafts pending reviewed approval; defer affected work without a blocking prompt in unattended runs. Do not run `setup-skills` merely to capture the reference.

## Red flags: stop and correct

| Thought | Reality |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| "Approved context is missing, so screenshots stay uncaptured" | Capture first; fresh unattended context follows the app's scoped exception. |
| "Step 1: run setup-skills" | Not for this task. The capture phase produces context. |
| "Fetch got 403, use web search / indexed pages" | Use the isolated browser for that origin. Search results are not the site. |
| "Raw HTML is enough to find the links" | Menus and mobile navigation render at runtime. Discover in the browser. |
| "The MCP is configured isolated, so captures are isolated" | Prove it at runtime before the first visit (discover workflow). |
| "Ask about every minor choice" | Use stated defaults; unattended runs never issue blocking questions. |
| "Capture every page in full at both widths" | Full captures for family representatives only. Members get content extraction. |
| "The canvas preflight always stops local work" | Explicitly authorized unattended runs have a narrow local-preview exception. |
| "Canvas is not in my tool list, so it is missing" | Run the canvas capability lookup before concluding anything. |
| "Headless means I have permission" | Honor explicit authorization, not execution mode or silence. |
| "Capture every filter option / every FAQ open" | One screenshot per kind of state, at most 8 per representative. |
| "Each page looks a bit different, so it is its own family" | Compare section types in order. More families than half the pages is too fine. |
| "Inner layouts are simplified; I'll note it in differences" | A representative missing a section, layout or image is a defect. Fix it first. |
| "One generic renderer can serve every family" | One composition per family, passing the representative gate. |
| "This file is huge; stop to ask" | Keep originals to 25 MiB; larger served copies default to under 25 MiB. |
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
import { readFileSync, realpathSync } from "node:fs"
import { resolve } from "node:path"
import { pathToFileURL } from "node:url"

const DECISIONS = new Set(["build", "stub-external", "stub-auth", "stub-download", "deferred"])
const STATUSES = new Set(["planned", "built", "verified", "blocked"])
const FINAL_STATUSES = new Set(["verified", "blocked"])
const LOCAL_BOUNDARIES = new Set(["stub-auth", "stub-download", "deferred"])

export function checkLedger(ledger, { final = false } = {}) {
const problems = []

if (typeof ledger.source !== "string") problems.push("source: missing source URL")
if (!ledger.browser || ledger.browser.cookies !== 0) {
problems.push("browser: runtime isolation proof missing or cookies were present")
}
Comment thread
Copilot marked this conversation as resolved.
Resolved
if (!ledger.access || Object.keys(ledger.access).length === 0) {
problems.push("access: no access method recorded")
}
if (!Array.isArray(ledger.pages) || ledger.pages.length === 0) {
problems.push("pages: no destinations recorded")
return problems
}

const families = new Map()
const routes = new Map()
const urls = new Set()
for (const [index, page] of ledger.pages.entries()) {
const label = page.url ?? `pages[${index}]`
if (urls.has(page.url)) problems.push(`${label}: listed more than once`)
urls.add(page.url)
Comment thread
Copilot marked this conversation as resolved.
Resolved
if (!DECISIONS.has(page.decision))
problems.push(`${label}: unknown decision "${page.decision}"`)
if (!Array.isArray(page.foundIn) || page.foundIn.length === 0)
problems.push(`${label}: foundIn is empty`)
if (page.decision !== "build" && !LOCAL_BOUNDARIES.has(page.decision)) continue
Comment thread
Copilot marked this conversation as resolved.
Resolved

const kind = page.decision === "build" ? "build page" : "local boundary"
if (
typeof page.route !== "string" ||
!page.route.startsWith("/") ||
page.route.startsWith("//") ||
page.route.includes("\\") ||
/[\u0000-\u001f\u007f]/.test(page.route)
)
problems.push(`${label}: ${kind} has no local route`)
if (!STATUSES.has(page.status)) problems.push(`${label}: unknown status "${page.status}"`)
if (final && !FINAL_STATUSES.has(page.status))
problems.push(`${label}: status "${page.status}" is not final`)
if (page.status === "blocked" && !page.note) problems.push(`${label}: blocked without a note`)

if (routes.has(page.route))
problems.push(`${label}: route ${page.route} also used by ${routes.get(page.route)}`)
routes.set(page.route, label)
if (page.decision !== "build") continue

if (typeof page.family !== "string") problems.push(`${label}: build page has no family`)
const family = families.get(page.family) ?? { representatives: 0 }
if (page.representative) family.representatives += 1
families.set(page.family, family)
}

for (const [name, family] of families) {
if (family.representatives !== 1) {
problems.push(
`family ${name}: needs exactly one representative, found ${family.representatives}`,
)
}
}

return problems
}

function summarize(ledger) {
const counts = {}
for (const page of ledger.pages ?? []) {
const key = page.decision === "build" ? `build/${page.status}` : page.decision
counts[key] = (counts[key] ?? 0) + 1
}
return counts
}

if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
const args = process.argv.slice(2)
const final = args.includes("--final")
const path = resolve(args.find((arg) => !arg.startsWith("--")) ?? "reference/coverage.json")

let ledger
try {
ledger = JSON.parse(readFileSync(path, "utf8"))
} catch (error) {
console.error(`Cannot read ledger ${path}: ${error.message}`)
process.exit(2)
}

const problems = checkLedger(ledger, { final })
console.log(JSON.stringify(summarize(ledger)))
if (problems.length > 0) {
for (const problem of problems) console.error(problem)
process.exitCode = 1
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
import assert from "node:assert/strict"
import { spawnSync } from "node:child_process"
import { copyFileSync, mkdirSync, mkdtempSync, rmSync } from "node:fs"
import { tmpdir } from "node:os"
import { join } from "node:path"
import { test } from "node:test"
import { fileURLToPath } from "node:url"

import { checkLedger } from "./check-ledger.mjs"

function ledger(pages) {
return {
source: "https://example.com/",
browser: { cookies: 0, pages: 1, checkedAt: "2026-01-01T00:00:00Z" },
access: { "https://example.com": "browser" },
pages,
}
}

const hub = {
url: "https://example.com/cards",
foundIn: ["header"],
family: "hub",
representative: true,
decision: "build",
route: "/cards",
status: "verified",
}

test("accepts a complete final ledger", () => {
const pages = [
hub,
{
...hub,
url: "https://example.com/loans",
route: "/loans?term=12#details",
representative: false,
},
{ url: "https://example.org/", foundIn: ["footer"], decision: "stub-external" },
{
url: "https://login.example.com/",
foundIn: ["header"],
decision: "stub-auth",
route: "/login",
status: "verified",
},
]
assert.deepEqual(checkLedger(ledger(pages), { final: true }), [])
})

test("rejects a ledger without runtime isolation proof", () => {
const value = { ...ledger([hub]), browser: undefined }
assert.match(checkLedger(value).join("\n"), /isolation proof/)
})

test("rejects planned pages at handoff but not during discovery", () => {
const pages = [{ ...hub, status: "planned" }]
assert.deepEqual(checkLedger(ledger(pages)), [])
assert.match(checkLedger(ledger(pages), { final: true }).join("\n"), /not final/)
})

test("requires exactly one representative per family", () => {
const pages = [hub, { ...hub, url: "https://example.com/loans", route: "/loans" }]
assert.match(checkLedger(ledger(pages)).join("\n"), /exactly one representative/)
})

test("rejects a URL listed under two decisions", () => {
const pages = [hub, { url: hub.url, foundIn: ["header"], decision: "stub-auth" }]
assert.match(checkLedger(ledger(pages)).join("\n"), /listed more than once/)
})

test("rejects duplicate routes and unexplained blocks", () => {
const pages = [
hub,
{ ...hub, url: "https://example.com/x", representative: false, status: "blocked" },
]
const problems = checkLedger(ledger(pages)).join("\n")
assert.match(problems, /also used by/)
assert.match(problems, /blocked without a note/)
})

test("requires a local route and final status for local boundaries", () => {
const login = { url: "https://login.example.com/", foundIn: ["header"], decision: "stub-auth" }
const missing = checkLedger(ledger([hub, login]), { final: true }).join("\n")
assert.match(missing, /login\.example\.com\/: local boundary has no local route/)
assert.match(missing, /login\.example\.com\/: unknown status/)

const planned = { ...login, route: "/login", status: "planned" }
assert.match(checkLedger(ledger([hub, planned]), { final: true }).join("\n"), /not final/)
})

test("rejects a route that is not a local path", () => {
for (const route of [
"https://example.com/cards",
"//external.example/cards",
"/\\external.example/cards",
"/\t/external.example/cards",
]) {
const pages = [{ ...hub, route }]
assert.match(checkLedger(ledger(pages)).join("\n"), /no local route/, JSON.stringify(route))
}
})

test("checks the ledger when run from a path with spaces", (t) => {
const directory = mkdtempSync(join(tmpdir(), "check ledger "))
t.after(() => rmSync(directory, { recursive: true, force: true }))
const script = join(directory, "with space", "check-ledger.mjs")
mkdirSync(join(directory, "with space"))
copyFileSync(fileURLToPath(new URL("./check-ledger.mjs", import.meta.url)), script)
const result = spawnSync(process.execPath, [script, join(directory, "missing.json")], {
encoding: "utf8",
})
assert.equal(result.status, 2, result.stderr)
})
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# Build

## Canvas

Follow the [shared canvas preflight](../../../../REPLICA.md#canvas-preflight), discovering actual capabilities rather than judging from the advertised tool list. Use the Replica canvas when available. Its missing-canvas exception applies only to explicitly authorized unattended local runs: explain recovery once, then continue with the local preview without waiting or changing plugin settings. Hosts without canvas support retain the ordinary local-preview fallback.

The Replica preview and browser inspection are separate. Use the [shared browser workflow](../../browser-canvas-validation/WORKFLOW.md) for rendered checks; a missing Replica canvas does not waive browser isolation or permit claiming unavailable checks passed.

## Implement

Use the [create-prototype](../../create-prototype/SKILL.md) create workflow with the selected active context and captured task evidence. Preserve existing guidance; missing or conflicting required context blocks only the affected work. In unattended runs, record that limitation and continue independent supported work without a question.

Follow the app's `AGENTS.md` and shared authoring rules. Reuse existing components and supported design-system APIs when available; Minimal needs no added component library. Build editable React compositions with page content separate from presentation. Captured page HTML is reference evidence, not the app's rendering implementation.

Order:

1. Shared shell: header, menus, footer, mobile navigation, tokens and fonts.
2. One composition per family, from its representative capture. Pass the
representative gate below before step 3. A single generic renderer for
every family is not a composition.
3. Every `build` page as a route using its own `content.json` as seed data.
4. Stubs: outbound links stay outbound; `stub-auth`, `stub-download` and
`deferred` pages render a local boundary at their ledger route that names
the original URL.

Every link in the shell must resolve to a built route or a stub. Real
submissions stay disabled. Update the `status` of each row with a local route,
boundaries included, to `built` as routes land.

## Representative gate

Before building a family's other pages, capture its representative locally at
both viewports and compare it with the source capture section by section.
Every source section must be present, in order, with the same layout type
(image beside text, card grid with the same column count, carousel with its
controls, numbered steps, accordion) and its own images and calls to action in
place. A missing section, flattened layout or missing image is a build defect:
fix the family composition, not the differences report. Members inherit
whatever the representative gets wrong.

## Compare once

After the gate, for each representative check:

- every header, menu and footer link resolves;
- section order and headings match;
- key geometry (header height, content width, hero position) within a few
pixels.

Fix navigation gaps and broken routes. Record only residual visual differences
(spacing, image crops, glyphs, a few pixels) in `reference/differences.md`
instead of iterating on polish. Set rows to `verified` or `blocked` with a note.
Comment thread
Copilot marked this conversation as resolved.
Resolved

## Handoff

Run the app's declared type check, tests, build and formatting check before handoff. Fix failures and report unavailable checks; a passing ledger does not replace them.

`node .agents/skills/create-prototype-from-production/scripts/check-ledger.mjs --final` must pass. When authorized, commit the build separately from the capture commit. Report ledger counts by decision and status, the difference list, assets over 1 MB, defaults applied, deferred operations, unavailable checks, commit status, and the preview URL when running. Blocked work is not a completed build.
Loading
Loading