Spec → Plan → Build

The canonical Zeq workflow. Every user-facing entry point — the homepage wizard, the Pulse, the workbench composer, the CLI — funnels through it. If you're reading the SDK to build with Zeq, this is the loop to internalise first.

The cheap-turn rule

A chat turn is llm_page_chat (5 compute units); a page build is llm_html_generation (30 units). Everything is complexity-priced in credits — units × the live compute price, resolved at call time. A build costs about six chat turns, so the architect-together loop trades a few cheap turns up front for the certainty that the expensive build hits intent on the first try, not the third. The conversation is always cheaper than the rebuild.

The three modes

The Pulse surfaces these as a mode chip — SKILL / PLAN / BUILD — that the visitor can flip explicitly, or that the agent advances automatically as the conversation matures.

Mode	What's happening	Operation (complexity-priced)
SKILL	The visitor describes what they want. The agent clarifies, then proposes a spec — inputs, outputs, regime, success criteria. No build call yet.	`llm_page_chat` — 5 units
PLAN	Spec is locked. The agent proposes a plan — design pattern, operators (or a synthesised skill), engine, runtime API calls, fail-safe behaviour. The visitor refines or approves.	`llm_page_chat` — 5 units · plus `skill_synthesis` if a skill needs synthesising
BUILD	Plan is approved. One `generate-html` call, grounded in the spec + plan as a system message so the build cannot drift. Page deploys. Footer cites the skill + proof.	`llm_html_generation` — 30 units

The 8-step loop

Borrowed from spec-driven development, adapted for the envelope economy.

1. Visitor describes what they want.            (free — first message)
        ↓
2. Agent clarifies — smallest set of questions  (chat turn)
   that would change the build if answered
   differently. One or two per round, max.
        ↓
3. Agent proposes a SPEC.                       (chat turn)
   Inputs · Outputs · Regime · Success criteria.
   Shown to visitor as a short bulleted readout.
        ↓
4. Visitor refines. "More sensitive to X."      (chat turn each)
   Each round is a cheap chat turn.
        ↓
5. Agent proposes a PLAN.                       (chat turn, plus
   Pattern · Operators · Engine · API calls ·    skill_synthesis if a
   Fail-safe when owner wallet hits 0.           skill is synthesised)
        ↓
6. Visitor approves the plan.                   (—)
   Explicit "build it" — wizard surfaces a
   confirm button labelled "Build →".
        ↓
7. Agent builds. One generate-html call.        (build — 30 units)
   Spec + plan passed as system message.
        ↓
8. Plan + skill_id cited in the page footer.    (—)
   Anyone replaying can see what was asked for
   and what was built.

A clean run — three clarification turns, one spec, one plan, one build — costs roughly two builds' worth of credits. Compared to a misfired build that the visitor rebuilds twice (two full builds with nothing useful in between, then the turns anyway), the loop is dramatically cheaper.

Where the loop is implemented

You can enter this loop from any of three surfaces. They share the same backend (the page-chat endpoint with the agent-context loader), so a conversation started in one can be picked up in another.

Surface	URL	When to use it
Homepage wizard	`/` (step 5 onward)	First-time visitors. Walks the loop explicitly with numbered steps and starter prompts.
Pulse	The mint chip on every page · `/apps/zeq-orb/`	Re-entering the loop from any page on the network. Carries page context.
Workbench Pulse tab	Press `?` on `/s/<machine>/` · or the workbench tab	Operating on a machine you already own. Has direct access to the workbench's Files / Pages / Queries / APIs / CLI panes.
CLI	`/apps/cli/` · `zeq` command in the workbench	Programmatic / scriptable. Same loop, terminal-shaped.

When to synthesise a skill vs. compose from the catalogue

The framework ships 1,500+ catalogued operators across 64 domains. Most visitor requests can be served by composing 3–4 of them. A skill (synthesised operator pack) is only minted when the catalogue doesn't cover the visitor's intent.

Use the catalogue (the cheapest compute)	Synthesise a skill (`skill_synthesis`, one-time)
Standard physics — orbits, pendulums, EM waves	Visitor's domain isn't in the catalogue (custom industry — RPA workflows, niche bio assays)
Visitor's problem maps to named operators	Novel composition of existing math under a new label
3 or fewer operators close the problem	5+ operators with a custom equation tying them together
Visitor wants to read what was used	Visitor wants the answer, not the operator list

Rule of thumb: try catalogue composition first. Only call /api/zeq/skills/synthesise when you cannot find 3–4 named operators that fit.

Citation — every built page carries its receipts

The plan and skill_id are not discarded after the build. They're written into the page footer so anyone replaying later can verify exactly what was asked for and what was built.

<footer class="zeq-attribution">
  <details>
    <summary>Built on Zeq · KO42 · ≤ 0.1% precision</summary>
    <ul>
      <li>Pattern: <code>B — Interactive Simulation</code></li>
      <li>Skill: <code>Drought-Yield Response</code> ·
         <code>skill_id 8a3f…2c91</code></li>
      <li>Operators: <code>KO42 · CLIM-RAD-001 · BIO-PHOTO-014 · STAT-COX-002</code></li>
      <li>Built at zeqond <code>Z2288977443</code></li>
      <li>ZeqProof <code>a1b2c3…64chars</code> ·
        <a href="/api/zeq/verify?proofDigest=a1b2c3…">verify</a></li>
    </ul>
  </details>
</footer>

This is the same anti-hallucination contract that runs through the whole framework: every state transition carries a proof, every page carries an audit trail, every operator call is replayable. Nothing the agent ships is unattributable.

What the agent must NEVER do

Codified so visitors know what to expect — and so anyone forking the Pulse and building their own architect can match the contract.

Never call generate-html immediately on a fresh visitor prompt. Always at least one round of clarify + spec.
Never synthesise a skill on the FIRST visitor message. Synth only after the spec is clear and the catalogue gap is confirmed.
Never hide costs. Every step that spends credits shows its live resolved price in the conversation: "Synthesising a custom skill (…)", "Building the page (…)".
Never rebuild on a small refinement. If the visitor's tweak is "change the slider colour" or "make the chart wider", that's an edit-mode chat turn, not a fresh build at six times the price. Use page-chat in edit mode on the deployed page.
Never omit the citation footer. Every built page carries the attribution block above.

A worked dialogue — what "architect together" actually looks like

Visitor: I want a tool that predicts wheat yield under drought.

Agent (SKILL mode — chat turn): Got it — drought-yield simulator. Three quick questions so the build matches your intent:

Region: temperate (UK / Northern Europe / US Midwest), or generic?

Time horizon: single growing season, or multi-year with climate scenarios?

Audience: a farm operator picking sowing date, or a researcher exploring parameter sensitivities?

Visitor: UK. Single season. Farm operator.

Agent (proposing spec — chat turn):

Spec:

Inputs: sowing date · soil-moisture profile (slider 0–1) · forecast temperature curve · fertiliser plan

Outputs: weekly yield curve (kg/ha) · risk-of-failure probability · recommended irrigation schedule

Regime: environmental + biological coupling under KO42

Success: the farmer can move sliders and see the yield curve respond in real time without server round-trips

Confirm or refine.

Visitor: Looks good. Make sure the irrigation schedule shows water-cost trade-off too.

Agent (PLAN mode, after skill synth — skill_synthesis + a chat turn): Catalogue gives me CLIM-RAD-001 + BIO-PHOTO-014 but no irrigation trade-off math; I'll synthesise a Drought-Yield-with-Irrigation skill (one-time skill_synthesis — reusable on future edits).

Plan:

Pattern: B — Interactive Simulation with side panel for parameters

Skill: new Drought-Yield-with-Irrigation (4 operators + irrigation cost coupling)

Engine: Chart.js (one chart, lightweight)

API calls at runtime: /api/zeq/compute on slider change, debounced 250 mz; /api/zeq/pulse for the system-clock pill

Owner cost at runtime: each slider movement is one catalogue compute — the cheapest operation; even a busy farmer hammering it stays well within the daily credit claim

Fail-safe: if owner wallet hits 0, freeze sliders, banner "owner's wallet is empty"

Build now? (the resolved build price is shown live)

Visitor: Build.

Agent (BUILD mode — one build, ~60 Zeqonds): [single generate-html call, grounded in spec + plan + skill_id. Returns HTML. Page deployed. Footer cites skill_id + proof digest.]

Total: a handful of chat turns + one skill synthesis + one build. Without the architect-together loop, the visitor would have burned a full build on a wrong page, then a second full build to fix it — and probably ended up with a yield model that didn't show the irrigation cost trade-off at all.

Cross-references

Concept	Where it lives
Chat-turn and build pricing (complexity-priced compute units)	Tally tokens
Design patterns A–E to propose in the plan stage	`05-PATTERNS.md` (agent-context)
JS engines (Chart.js, anime.js, Three.js…) to propose	`06-ENGINES.md` (agent-context)
The skill synthesis endpoint	POST /api/zeq/skills/synthesise
The page-generation endpoint	POST /api/zeq/agent/generate-html
Pulse mode chip implementation	Pulse
Anti-hallucination layer	HF1–HF20 forensic operators

TL;DR

You don't talk to the Zeq agent the way you talk to a generic chatbot. You architect together. The agent clarifies, proposes a spec, refines, proposes a plan, gets explicit approval, and only then spends the expensive token on a build. Three modes — SKILL / PLAN / BUILD — make the stage you're in legible to both sides. Every built page carries its own audit trail.

Skill synthesis is a one-time investment. Plans are cheap. Builds are intentional. That's the contract.

Middleware active. Kernel on the 1.287 Hz HulyaPulse. Awaiting next Zeqond.

The three modes​

The 8-step loop​

Where the loop is implemented​

When to synthesise a skill vs. compose from the catalogue​

Citation — every built page carries its receipts​

What the agent must NEVER do​

A worked dialogue — what "architect together" actually looks like​

Cross-references​

TL;DR​