Soroe

Skills for “make it like these.” A deterministic compiler keeps every selected facet traceable.

Comment

Inspiration

Handing reference sites to a coding agent usually sounds like:

"Make it like these sites, but ours."

That intent is easy to lose. An agent may copy unselected details, miss the interaction the user actually wanted, or leave the user reviewing every pixel by hand. The missing piece is not another browser or coding tool—it is a repeatable method for observing references, selecting exact facets, adapting them responsibly, and verifying the result.

What it does

Soroe is a skills-first agent framework for "make it like these." It gives coding agents three focused skills backed by an offline, deterministic compiler:

  1. Soroe Design guides an agent to inspect references with whatever browser or visual tools are available, capture factual evidence, select independently adoptable facets, resolve conflicts, and compile a traceable design system.
  2. Soroe Build guides the agent to turn the Facet Pack into real code in the target repository, mapping logical targets to concrete files, components, and selectors.
  3. Soroe Verify guides the agent to execute the generated plan with whatever testing tools are available and record every check as passed, failed, blocked, or manually reviewed—with evidence.

Soroe does not try to replace Browser, Computer Use, Playwright, Chrome MCP, or frontend frameworks. It teaches agents how to use those capabilities with structure and discipline.

The deterministic compiler connects the stages with reviewable artifacts:

  • facet-pack.json
  • REFERENCE_GRAPH.md
  • DESIGN_BRIEF.md
  • tokens.css
  • IMPLEMENTATION_BRIEF.md
  • verification.plan.json
  • target-map.json
  • verification-results.json

Every selected facet points to source evidence, declares what must survive and what must not leak into the target, maps to implementation targets, and carries observable verification checks.

How we built it

Soroe is built with vanilla JavaScript on Node.js 20+ and has no production dependencies or runtime network calls. It includes:

  • JSON Schema and runtime validation for soroe.recipe/v1 and soroe.pack/v1
  • canonical JSON writers with sorted keys and LF normalization
  • SHA-256 recipe digests for reproducible builds
  • three self-contained Agent Skills under skills/design, skills/build, and skills/verify
  • a CLI with init, validate, design, build, and verify
  • 24 tests covering validation, deterministic output, phase boundaries, target maps, verification-result contracts, and CLI behavior
  • a benchmark implementation in Kuro's Querencia that dogfoods the workflow

How Codex and GPT-5.6 were used

Codex was the primary implementation partner throughout Build Week. It helped us:

  • inspect and critique the evolving product boundary
  • turn the original compiler-heavy concept into a skills-first agent framework
  • design the recipe, Facet Pack, target-map, and verification-result contracts
  • implement the CLI, runtime validators, deterministic writers, fixtures, and tests
  • dogfood the workflow against a real frontend repository
  • find inconsistencies between implementation, README, demo language, and submission claims

GPT-5.6 was especially valuable for the product-level reasoning: separating Soroe's responsibility from browser/testing tools, designing anti-copy guardrails, making verification honest about blocked checks, and shaping the agent instructions so they remain tool-agnostic.

Key decisions remain inspectable through the repository history, generated artifacts, and test suite.

Challenges we ran into

Defining the right boundary

Our first framing made Soroe sound like it should browse, screenshot, implement, and test everything itself. That was the wrong product. Soroe should guide an agent that already has those capabilities. The compiler is the deterministic kernel; the skills are the product experience.

Determinism

The same recipe must produce byte-identical artifacts so teams can diff, cache, audit, and review changes. We canonicalized JSON, normalized line endings, sorted graph structures, and added SHA-256 digests.

Reference without copying

"Make it like Stripe" is too broad. Soroe requires evidence-addressed facets and explicit include/exclude guardrails so an agent selects a particular structural or interaction decision without copying brands, prose, assets, source code, or an entire page.

Honest verification

A tool-dependent check that was not executed is not a pass. Soroe initializes those checks as blocked; the Verify skill resolves them with available tools and records evidence.

Accomplishments

  • Reframed Soroe as three focused, reusable Agent Skills
  • Built an offline deterministic compiler with zero production dependencies
  • Created a traceable reference → evidence → facet → target → check chain
  • Added an agent-owned target map connecting abstract design decisions to real code
  • Added a structured verification-results contract with honest statuses
  • Reached 24 passing tests and a one-command end-to-end judge check
  • Published the source under the MIT License

What we learned

  • Agents need procedural skills and contracts, not another paragraph describing a vibe.
  • Tool-agnostic guidance is more portable than coupling the product to one browser or framework.
  • Verification must be designed during facet selection, not added after implementation.
  • Explicit exclusions are as important as selected properties in reference-driven design.
  • Dogfooding a real site reveals workflow gaps that unit tests cannot.

Judge testing

Requirements: Node.js 20+ on macOS, Linux, or WSL.

git clone https://github.com/ken-kuro/soroe.git
cd soroe
npm install
npm test
npm run check

npm test runs 24 tests. npm run check validates the included recipe and exercises Design → Build → verification-results initialization without accounts, API keys, or network access.

For an agent-driven run, load the three skills in order:

  • skills/design/SKILL.md
  • skills/build/SKILL.md
  • skills/verify/SKILL.md

What's next

  • package Soroe as a native Codex skill pack/plugin
  • add reusable frontend mapping references for React, Vue, Svelte, and static sites
  • add a validation command for agent-resolved verification evidence
  • build a visual recipe-authoring and Reference Graph review experience
  • publish benchmark scenarios and evals for reference-to-interface fidelity

Links

Built With

Share this project:

Updates