From 99e53d534cff432b45076cde7aaa87135711a924 Mon Sep 17 00:00:00 2001 From: Mike Clay Date: Sat, 11 Jul 2026 09:55:40 +0100 Subject: [PATCH 01/12] Restore full shell width for documentation site prose. Remove the 65ch text column cap so body copy matches headings and diagrams across the site shell. --- site/style.css | 29 ----------------------------- 1 file changed, 29 deletions(-) diff --git a/site/style.css b/site/style.css index 5a0678a3..b2ec2784 100644 --- a/site/style.css +++ b/site/style.css @@ -83,33 +83,6 @@ body { line-height: 1.65; } -/* Readable prose measure; tables and diagrams stay full shell width */ -.prose, -.hero .lede, -main > p, -main > ul:not(.card-grid):not(.pill-row):not(.steps), -main > ol:not(.steps), -.card p, -.tool-summary, -.schema-summary, -.note { - max-width: 65ch; -} - -main > h1, -main > h2, -main > h3, -.breadcrumb, -.page-pagination, -.audience-badge, -.implementer-panel, -figure.diagram, -.table-wrap, -.card-grid, -.steps { - max-width: var(--shell); -} - /* Text and graphics both flow to the full shell width, left-aligned to the shell edge, so the page uses the available screen width consistently. */ h1, h2, h3 { @@ -342,7 +315,6 @@ main, background: var(--bg-inset); border: 1px solid var(--border); border-radius: var(--radius); - max-width: 65ch; } .implementer-panel > summary, @@ -372,7 +344,6 @@ main, border-radius: 0 var(--radius) var(--radius) 0; font-size: 0.95rem; color: var(--text-muted); - max-width: 65ch; } .card-grid--personas { From 5a799d1f43d17e39376b6490ec576e64b1e4f41f Mon Sep 17 00:00:00 2001 From: Mike Clay Date: Sat, 11 Jul 2026 09:58:11 +0100 Subject: [PATCH 02/12] Simplify API tool descriptions on the documentation site. Add site-specific plain-language guides and shorter parameter hints in the site generator while keeping MCP source schemas authoritative. --- scripts/generate-site-data.ts | 152 +++++++++++++++++++++++++++++-- site/api/tools.html | 162 +++++++++++++++++++++------------- 2 files changed, 246 insertions(+), 68 deletions(-) diff --git a/scripts/generate-site-data.ts b/scripts/generate-site-data.ts index 9bf673b7..a8efb70e 100644 --- a/scripts/generate-site-data.ts +++ b/scripts/generate-site-data.ts @@ -283,6 +283,130 @@ const TOOL_GROUPS: Array<{ title: string; note: string; tools: string[] }> = [ { title: 'Trace', note: 'Execution history for debugging and audit.', tools: ['get_trace'] }, ]; +/** Plain-language one-line summaries for the site (source descriptions stay authoritative for MCP). */ +const SITE_TOOL_SUMMARIES: Partial> = { + start_session: 'Start or resume a workflow session.', + dispatch_child: 'Start a child workflow inside the current session.', + get_activity: 'Load the current activity definition, including steps and transitions.', +}; + +/** Readable full descriptions for the site. Parameter tables still come from source schemas. */ +const SITE_TOOL_GUIDES: Partial> = { + discover: [ + 'Call this first. Returns the server name, version, and the bootstrap steps for starting a workflow.', + 'No session required. Use `list_workflows` to see what you can run.', + ], + list_workflows: [ + 'Lists every workflow the server can run, with id, title, version, and tags.', + 'If some workflow files cannot be loaded, you still get the working entries plus a `load_errors` list for the failures.', + ], + health_check: [ + 'Quick ping to confirm the server is up. Returns status, name, version, workflow count, and uptime.', + 'No session required.', + ], + start_session: [ + 'Opens a new workflow session or resumes an existing one.', + 'Returns a `session_index` (six characters), basic workflow metadata, and `planning_folder_path` — the absolute path where the server stores session artifacts.', + 'Pass `planning_folder` as any absolute path whose basename is your planning slug (for example, `.../planning/2026-05-28-my-slug`). Only the slug is used; the server resolves it under its own workspace. A stale or wrong path prefix is harmless.', + 'If that slug already has `session.json`, the session resumes and `workflow_id` is ignored. Otherwise the server creates a fresh session and seeds variables from the workflow defaults.', + 'Omit `planning_folder` to start a meta bootstrap session in a temp folder. Use `dispatch_child` later to promote it to a real planning folder.', + 'Child workflows are started with `dispatch_child`, not `start_session`.', + ], + get_workflow_status: [ + 'Returns whether the session is active, blocked at a checkpoint, or completed, plus the current activity and completed steps.', + 'If the session is nested under a parent, parent context is included too.', + ], + dispatch_child: [ + 'Starts a child workflow inside the parent session you are already in.', + 'Returns the child\'s `session_index` and `planning_folder_path`. The child\'s variables are seeded from the child workflow\'s defaults; the parent is unchanged.', + 'The child state is stored inside the parent\'s `session.json` under `triggeredWorkflows`.', + 'When the parent is a temporary meta-bootstrap session, the server first promotes it to a real planning folder on disk, then embeds the child. You can keep using the parent\'s original `session_index`.', + ], + get_workflow: [ + 'Loads the workflow definition for the current session.', + 'The response starts with the orchestrator technique, then a separator, then metadata: rules, variables, `initialActivity` (the first activity to run), and a short list of all activities.', + 'Use `initialActivity` for your first `next_activity` call — this is the only tool that returns it.', + 'Also returns `planning_folder_path`. Treat this as the one true artifact location; do not build paths relative to your own working directory.', + 'If some activity files failed to load, `activity_load_errors` lists them and those activities are omitted from the list.', + ], + next_activity: [ + 'Moves the session to a new activity. This is the orchestrator\'s advance call — it updates state and records the trace but does not return the activity body.', + 'After `next_activity`, the worker should call `get_activity` to load steps, checkpoints, transitions, and technique references.', + 'For the first transition, use `initialActivity` from `get_workflow`. After that, use ids from the current activity\'s `transitions`.', + 'Optional `step_manifest` and `transition_condition` help the server validate what you completed. Manifest checks are advisory — mismatches produce warnings, not hard errors.', + ], + get_activity: [ + 'Loads the full definition for whatever activity the session is currently on. No `activity_id` parameter — the server reads it from session state.', + 'You must pass `context_tokens`: your worker\'s context window size in tokens. The server uses this to decide how many step techniques to bundle inline.', + 'Ungated techniques that fit the budget are included in the response under `step_techniques` — the same content you would get from `get_technique` for that step. Gated steps and overflow techniques still need a separate `get_technique` call.', + 'If the session uses persistent context mode (or you pass `bundle: "reference"`), content you already received may come back as short unchanged markers instead of full text. Pass `bundle: "full"` to force full delivery.', + ], + yield_checkpoint: [ + 'Call when a checkpoint step tells you to stop and hand control to the orchestrator.', + 'Records the checkpoint as active and returns the `session_index` for a `` block in your output.', + ], + resume_checkpoint: [ + 'Call after the orchestrator resolves a checkpoint and resumes you.', + 'Verifies the checkpoint is cleared and returns any variable updates to apply before continuing the activity.', + ], + present_checkpoint: [ + 'Loads the active checkpoint\'s message, options, and effects so you can show it to the user.', + 'Reads from `state.activeCheckpoint` — no separate checkpoint handle is needed.', + ], + respond_checkpoint: [ + 'Submits the user\'s checkpoint decision and clears the active checkpoint.', + 'Present the checkpoint to the user and wait for input before calling this.', + 'Provide exactly one of: `option_id` (user picked an option), `auto_advance` (timer elapsed on a checkpoint with a default), or `condition_not_met` (conditional checkpoint whose condition was false).', + 'Variable effects from the chosen option are applied; type mismatches produce warnings in `_meta.validation` but do not block the response.', + ], + get_technique: [ + 'Fetches one technique for the current workflow or activity.', + 'Before any activity is active, returns the workflow\'s first technique. During an activity, use `step_id` to fetch a specific step\'s technique, or omit `step_id` for the activity\'s first technique.', + 'The response is fully composed: inherited inputs/outputs and merged rules from ancestor techniques, plus binding annotations when fetched via a step.', + 'Techniques load one at a time. In persistent context mode, an identical refetch may return a short unchanged marker; pass `full: true` to get the full payload again.', + 'Every fetch is recorded for trace and advisory manifest checks on the next `next_activity` call.', + ], + get_resource: [ + 'Loads reference material by id — templates, guides, or other markdown resources linked from techniques.', + 'Bare ids (`review-mode`) resolve within the current workflow. Prefixed ids (`meta/bootstrap-protocol`) load from another workflow.', + 'Add `#section` to fetch one heading slice instead of the whole file.', + 'Each fetch is logged for observability only; nothing validates that you called it.', + ], + get_trace: [ + 'Returns the tool-call history for debugging or audit.', + 'Pass accumulated `trace_tokens` from `next_activity` responses to reconstruct a specific segment. Omit them to read the live in-memory trace for the session.', + ], +}; + +/** Shorter parameter descriptions for the site tables (schemas in source stay authoritative). */ +const SITE_PARAM_HINTS: Record = { + session_index: 'Six-character token from `start_session`. Use the same value for every call in this session.', + workflow_id: 'Workflow id to run or dispatch (for example, `work-package`).', + planning_folder: 'Absolute path whose basename is the planning slug. The server resolves the slug under its own workspace — the directory prefix is only a hint.', + agent_id: 'Label for this agent in the session trace.', + context_mode: '`persistent`: reuse earlier deliveries when one agent keeps full context. `fresh` (default): always return full content.', + planning_slug: 'Slug for the promoted planning folder when dispatching from a meta bootstrap session. Ignored if the parent already has a persistent folder.', + activity_id: 'Activity to move to. First call: use `initialActivity` from `get_workflow`. Later: use an id from `transitions`.', + transition_condition: 'The condition name that led to this transition, from the previous activity.', + step_manifest: 'Steps completed in the previous activity, for example `[{ "step_id": "detect-review-mode", "output": "is_review_mode=false" }]`. Omit if no steps ran.', + 'step_manifest[].step_id': 'Step id from the activity definition (field name is `step_id`, not `id`).', + 'step_manifest[].output': 'Short summary of what the step produced. Use a JSON object when the step has multiple outputs.', + activity_manifest: 'History of completed activities with outcomes and transition conditions.', + 'activity_manifest[].activity_id': 'Completed activity id.', + 'activity_manifest[].outcome': 'Short outcome summary for that activity.', + 'activity_manifest[].transition_condition': 'Condition that led out of that activity, if any.', + context_tokens: 'Your worker context window in tokens. Required so the server can size inline technique bundling.', + bundle: '`reference`: return unchanged markers for content already delivered. `full`: always return complete text.', + checkpoint_id: 'Id of the checkpoint step you are yielding.', + option_id: 'Option the user selected. Must match one of the checkpoint\'s defined options.', + auto_advance: 'Set `true` to use the checkpoint\'s default option after its timer elapses.', + condition_not_met: 'Set `true` to dismiss a conditional checkpoint whose condition evaluated to false.', + step_id: 'Step within the current activity. Omit to get the first technique for the activity or workflow.', + full: 'Force full technique content even when persistent mode would return an unchanged marker.', + resource_id: 'Resource slug, optionally workflow-prefixed (`meta/bootstrap-protocol`), optionally with `#section` anchor.', + trace_tokens: 'Tokens collected from `next_activity` `_meta.trace_token` responses.', +}; + // --------------------------------------------------------------------------- // HTML rendering @@ -301,6 +425,17 @@ function firstSentence(text: string): string { return trimmed.length > 160 ? `${trimmed.slice(0, 157)}…` : trimmed; } +function siteParamDescription(label: string, fallback?: string): string { + if (SITE_PARAM_HINTS[label]) return SITE_PARAM_HINTS[label]; + const base = label.split('.').pop() ?? label; + if (SITE_PARAM_HINTS[base]) return SITE_PARAM_HINTS[base]; + return fallback ?? '-'; +} + +function renderGuideParagraphs(paragraphs: string[]): string { + return paragraphs.map(p => `

${richText(p)}

`).join('\n'); +} + function typeLabel(prop: JsonSchemaNode): string { if (prop.$ref) return prop.$ref.split('/').pop() ?? 'object'; if (prop.enum) return prop.enum.map(v => JSON.stringify(v)).join(' | '); @@ -326,7 +461,8 @@ function paramRows(schema: JsonSchemaNode, prefix = '', topLevelOnly = false): s const label = `${prefix}${name}`; if (topLevelOnly && prefix !== '') continue; const notes: string[] = []; - if (prop.description) notes.push(richText(prop.description)); + const hint = siteParamDescription(label, prop.description); + if (hint !== '-') notes.push(richText(hint)); if (prop.default !== undefined) notes.push(`Default: ${escapeHtml(JSON.stringify(prop.default))}`); rows.push( ` ${escapeHtml(label)}${escapeHtml(typeLabel(prop))}` + @@ -356,16 +492,22 @@ function renderParamTable(schema: JsonSchemaNode, topLevelOnly: boolean): string function renderTool(tool: CapturedTool): string { const lines: string[] = []; - const summary = firstSentence(tool.description); - const hasLongDescription = tool.description.length > summary.length + 20; + const siteGuide = SITE_TOOL_GUIDES[tool.name]; + const summary = SITE_TOOL_SUMMARIES[tool.name] ?? firstSentence(tool.description); + const hasSiteGuide = siteGuide !== undefined && siteGuide.length > 0; + const hasLongSource = tool.description.length > summary.length + 20; lines.push(`
`); lines.push(`

${escapeHtml(tool.name)}

`); lines.push(`

${richText(summary)}

`); - if (hasLongDescription) { + if (hasSiteGuide || hasLongSource) { lines.push('
'); lines.push(' Full description'); - lines.push(`

${richText(tool.description)}

`); + if (hasSiteGuide) { + lines.push(renderGuideParagraphs(siteGuide)); + } else { + lines.push(`

${richText(tool.description)}

`); + } lines.push('
'); } else if (tool.description !== summary) { lines.push(`

${richText(tool.description)}

`); diff --git a/site/api/tools.html b/site/api/tools.html index 66a8c929..a370d602 100644 --- a/site/api/tools.html +++ b/site/api/tools.html @@ -112,7 +112,8 @@

discover

Entry point for this server.

Full description -

Entry point for this server. Call this before any other tool to learn the bootstrap procedure for starting a session. Returns the server name, version, and the bootstrap guide explaining the full tool-calling sequence. Use list_workflows to discover available workflows. No parameters required and no session_index needed.

+

Call this first. Returns the server name, version, and the bootstrap steps for starting a workflow.

+

No session required. Use list_workflows to see what you can run.

No parameters.

@@ -121,7 +122,8 @@

list_workflows

List all available workflow definitions with their ID, title, version, and tags.

Full description -

List all available workflow definitions with their ID, title, version, and tags. Use this when you need to discover or filter available workflows. Returns an array of workflow summaries with tag-based categorization. If any workflow definition fails to load (unreadable file or manifest missing id/title/version), the response is instead an object with workflows (the loadable entries) and load_errors (one entry per failed file). Does not require a session_index.

+

Lists every workflow the server can run, with id, title, version, and tags.

+

If some workflow files cannot be loaded, you still get the working entries plus a load_errors list for the failures.

No parameters.

@@ -130,7 +132,8 @@

health_check

Check server health and availability.

Full description -

Check server health and availability. Returns server status, name, version, number of available workflows, and uptime in seconds. Does not require a session_index. Use this to verify the server is running before starting a workflow.

+

Quick ping to confirm the server is up. Returns status, name, version, workflow count, and uptime.

+

No session required.

No parameters.

@@ -138,19 +141,24 @@

Session

Create, inspect, and extend workflow sessions.

start_session

-

Start or resume the TOP-LEVEL workflow session.

+

Start or resume a workflow session.

Full description -

Start or resume the TOP-LEVEL workflow session. Identifies the planning folder via planning_folder — an absolute path whose basename is the slug (e.g., /home/user/repo/.engineering/artifacts/planning/2026-05-28-my-slug → slug 2026-05-28-my-slug). Only the basename is consumed; the path part is a hint and is otherwise ignored, so a stale or off-workspace path passed by the agent is harmless. The server always resolves the slug against its own workspace planning root. Returns a 6-character base32 session_index for the root session, plus basic workflow metadata, plus the canonical server-side planning_folder_path (the absolute path of the folder under THIS server's workspace) — the agent can pick up the current location from this response without doing any path math. Behaviour: if a folder for that slug already exists under the server's workspace planning root with session.json, the server resumes it (workflow_id taken from state — caller cannot rebrand a live session). Otherwise the folder is created (for non-meta workflows) or a transient tmp folder is used (for meta-bootstrap), and a fresh session is written with its variable bag seeded from the workflow's declared defaultValues (recorded as a variables_seeded history event; resumes never re-seed). When planning_folder is omitted entirely, a fresh meta-bootstrap session is created in os.tmpdir() and a synthetic UUID slug is registered so subsequent dispatch_child calls can promote it. The full resolved absolute path is persisted as planningFolderPath inside session.json; on resume, if the folder has been renamed or moved within the planning root, the recorded value is silently overwritten with its current location. Other tools identify the session by session_index (returned here) — they do not need the path, because session.json carries it. Child workflows are not created through start_session — call dispatch_child({ session_index, workflow_id }) from inside the parent session to append a child under triggeredWorkflows[] (embedded inline; the whole work-package tree lives in the top-level session.json). If the resolved folder contains legacy workflow-state.json + .session-token artefacts, the server migrates them in place. The agent_id parameter is stored on session.json#agentId, distinguishing orchestrator from worker calls in the trace.

+

Opens a new workflow session or resumes an existing one.

+

Returns a session_index (six characters), basic workflow metadata, and planning_folder_path — the absolute path where the server stores session artifacts.

+

Pass planning_folder as any absolute path whose basename is your planning slug (for example, .../planning/2026-05-28-my-slug). Only the slug is used; the server resolves it under its own workspace. A stale or wrong path prefix is harmless.

+

If that slug already has session.json, the session resumes and workflow_id is ignored. Otherwise the server creates a fresh session and seeds variables from the workflow defaults.

+

Omit planning_folder to start a meta bootstrap session in a temp folder. Use dispatch_child later to promote it to a real planning folder.

+

Child workflows are started with dispatch_child, not start_session.

- - - - + + + +
ParameterTypeRequiredDescription
workflow_idstringnoOptional. Target workflow ID for a fresh top-level session (e.g., "work-package"). Defaults to "meta". Ignored when the slug already resolves to an existing session.json (the workflow is taken from the resumed state).
planning_folderstringnoOptional. Absolute path whose basename is treated as the planning slug. The path part is informational — the slug is resolved against the SERVER's own workspace planning root, not the path you pass. Bare slugs and relative paths are rejected. When omitted, the server mints a transitional UUID slug and registers it for the meta bootstrap session.
agent_idstringnoSets the agentId field inside the session state. Distinguishes agents sharing a session in the trace. Defaults to "orchestrator" if omitted. Default: "orchestrator"
context_mode"persistent" | "fresh"noOptional. Declares the delivery context model for the session. "persistent" opts into reference-not-repeat delivery: get_activity replaces bundle content already delivered to this session+agent with short { unchanged: true, content_hash } markers, and get_technique answers a byte-identical refetch with an unchanged-reference (full: true re-fetches). Use ONLY when a single agent context runs the whole session and retains earlier payloads in its own context. Omit (or pass "fresh") for disposable-worker topologies — every call then receives full content. On resume, a supplied value overwrites the recorded mode.
workflow_idstringnoWorkflow id to run or dispatch (for example, work-package).
planning_folderstringnoAbsolute path whose basename is the planning slug. The server resolves the slug under its own workspace — the directory prefix is only a hint.
agent_idstringnoLabel for this agent in the session trace. Default: "orchestrator"
context_mode"persistent" | "fresh"nopersistent: reuse earlier deliveries when one agent keeps full context. fresh (default): always return full content.
@@ -160,33 +168,37 @@

get_workflow_status

Check the status of a workflow session.

Full description -

Check the status of a workflow session. Returns the session status (active/blocked/completed), current activity, completed activities trace, last checkpoint info, and parent context if nested. Requires a session_index.

+

Returns whether the session is active, blocked at a checkpoint, or completed, plus the current activity and completed steps.

+

If the session is nested under a parent, parent context is included too.

- +
ParameterTypeRequiredDescription
session_indexstringyesREQUIRED. The 6-character session_index returned by start_session. The server resolves this index to a planning folder under .engineering/artifacts/planning/ and reads/writes session.json there. The index is stable across all tool calls in the session — there is no rotation discipline.
session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.

dispatch_child

-

Dispatch a child workflow from the current session.

+

Start a child workflow inside the current session.

Full description -

Dispatch a child workflow from the current session. Pass session_index of the parent (any depth) and workflow_id of the child workflow. The server appends a child entry under the parent's triggeredWorkflows[] with the child's full SessionFile embedded inline (the entire work-package tree lives in the top-level session.json). The child's variable bag is seeded from the CHILD workflow's own declared defaultValues; the parent's bag is untouched. Returns the child's session_index, which the agent threads to subsequent authenticated tool calls operating on the child, plus the canonical planning_folder_path — the absolute path of the planning folder under THIS server's workspace (the .engineering root supplied at init). All work-package artifacts are written under that absolute path; the agent never composes the location relative to its CWD or the target component repo. Special case: when the parent is a transient orchestrator-bootstrap session (e.g. meta), the parent's state is promoted onto disk under a stable workspace planning folder before the child is embedded. The slug is taken from (in order): the optional planning_slug argument; the slug registered at start_session; a YYYY-MM-DD-<workflow-id> fallback. The parent's tmp folder is discarded post-promotion, but the parent's session_index is retained — the orchestrator can keep using its original index to authenticate subsequent calls (it resolves to the promoted folder for the lifetime of this server process). The on-disk shape matches the persistent-parent case — parent at the top of the file, child under triggeredWorkflows[0].state.

+

Starts a child workflow inside the parent session you are already in.

+

Returns the child's session_index and planning_folder_path. The child's variables are seeded from the child workflow's defaults; the parent is unchanged.

+

The child state is stored inside the parent's session.json under triggeredWorkflows.

+

When the parent is a temporary meta-bootstrap session, the server first promotes it to a real planning folder on disk, then embeds the child. You can keep using the parent's original session_index.

- - - - - + + + + +
ParameterTypeRequiredDescription
session_indexstringyesREQUIRED. The 6-character session_index returned by start_session. The server resolves this index to a planning folder under .engineering/artifacts/planning/ and reads/writes session.json there. The index is stable across all tool calls in the session — there is no rotation discipline.
workflow_idstringyesWorkflow id for the child (e.g. "work-package"). Must resolve to a workflow definition in the workflows directory.
agent_idstringnoagent_id stored on the child SessionFile. Defaults to "worker". Default: "worker"
planning_slugstringnoOptional. When the parent is a transient orchestrator-bootstrap session, the slug used for the promoted workspace folder. Takes precedence over any slug registered at start_session. Ignored when the parent is already persistent (the persistent parent owns the slug).
context_mode"persistent" | "fresh"noOptional. Delivery context model stored on the child SessionFile (see start_session). "persistent" activates reference-not-repeat delivery for calls against the child session; use ONLY when a single agent context executes the whole child workflow.
session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
workflow_idstringyesWorkflow id to run or dispatch (for example, work-package).
agent_idstringnoLabel for this agent in the session trace. Default: "worker"
planning_slugstringnoSlug for the promoted planning folder when dispatching from a meta bootstrap session. Ignored if the parent already has a persistent folder.
context_mode"persistent" | "fresh"nopersistent: reuse earlier deliveries when one agent keeps full context. fresh (default): always return full content.
@@ -198,13 +210,17 @@

get_workflow

Load the workflow definition for the current session.

Full description -

Load the workflow definition for the current session. The response begins with the resolved orchestrator technique bundle, then a --- separator, then lightweight workflow metadata: rules, variables, the initialActivity field (which activity to load first), and a stub list of all activities with their IDs and names. If any activity file failed to load (invalid or unparsable YAML), the response includes activity_load_errors listing each failed file with its error — those activities are absent from the activity list. Call this after start_session to learn the workflow structure — the initialActivity field in the response tells you which activity_id to pass to your first next_activity call. This is the only tool that provides initialActivity. The response also carries planning_folder_path: the canonical absolute planning folder for this session under THIS server's workspace .engineering root — bind it as the single artifact location and never recompose it relative to your CWD or the target component repo.

+

Loads the workflow definition for the current session.

+

The response starts with the orchestrator technique, then a separator, then metadata: rules, variables, initialActivity (the first activity to run), and a short list of all activities.

+

Use initialActivity for your first next_activity call — this is the only tool that returns it.

+

Also returns planning_folder_path. Treat this as the one true artifact location; do not build paths relative to your own working directory.

+

If some activity files failed to load, activity_load_errors lists them and those activities are omitted from the list.

- +
ParameterTypeRequiredDescription
session_indexstringyesREQUIRED. The 6-character session_index returned by start_session. The server resolves this index to a planning folder under .engineering/artifacts/planning/ and reads/writes session.json there. The index is stable across all tool calls in the session — there is no rotation discipline.
session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
@@ -214,17 +230,20 @@

next_activity

Transition to the specified activity.

Full description -

Transition to the specified activity. This is the orchestrator's tool for advancing the workflow — it validates the transition, advances the session state on disk, and records the trace, but does NOT return the activity definition. After calling next_activity, the worker should call get_activity to load the complete activity definition including steps, checkpoints, transitions, and technique references. For the first call, use the initialActivity value from get_workflow. For subsequent calls, use the activity IDs from the transitions field of the current activity's response. Optionally include a step_manifest summarizing completed steps and a transition_condition to enable server-side validation. Manifest validation also cross-checks fidelity (warn-only): a manifested technique step with no technique_fetched event recorded during the activity (see get_technique) — and no technique_bundled event from a bundling activity's get_activity — draws a warning.

+

Moves the session to a new activity. This is the orchestrator's advance call — it updates state and records the trace but does not return the activity body.

+

After next_activity, the worker should call get_activity to load steps, checkpoints, transitions, and technique references.

+

For the first transition, use initialActivity from get_workflow. After that, use ids from the current activity's transitions.

+

Optional step_manifest and transition_condition help the server validate what you completed. Manifest checks are advisory — mismatches produce warnings, not hard errors.

- - - - - + + + + +
ParameterTypeRequiredDescription
session_indexstringyesREQUIRED. The 6-character session_index returned by start_session. The server resolves this index to a planning folder under .engineering/artifacts/planning/ and reads/writes session.json there. The index is stable across all tool calls in the session — there is no rotation discipline.
activity_idstringyesActivity ID to transition to. For the first call, use initialActivity from get_workflow. For subsequent calls, use an activity ID from the transitions field of the current activity.
transition_conditionstringnoThe transition condition that led to this activity (from the transitions field of the previous activity). Enables server-side validation of condition-activity consistency.
step_manifestobject[]noArray of completed-step entries from the previous activity, e.g. [{"step_id":"detect-review-mode","output":"is_review_mode=false"}]. Each entry has two string fields: step_id (the literal id from the activity's steps[] — note the field is step_id, not id) and output. output is a short summary of what the step produced; for a step with more than one declared output, report a JSON object keyed by output id, e.g. {"step_id":"resolve-reference","output":"{\"reference_path\":\"lib/x\",\"component_name\":\"x\"}"}. Omit the parameter entirely when no steps ran; do not pass an empty array or empty string.
activity_manifestobject[]noActivity completion manifest from the orchestrator. Reports the sequence of activities completed so far with outcomes and transition conditions.
session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
activity_idstringyesActivity to move to. First call: use initialActivity from get_workflow. Later: use an id from transitions.
transition_conditionstringnoThe condition name that led to this transition, from the previous activity.
step_manifestobject[]noSteps completed in the previous activity, for example [{ "step_id": "detect-review-mode", "output": "is_review_mode=false" }]. Omit if no steps ran.
activity_manifestobject[]noHistory of completed activities with outcomes and transition conditions.
@@ -234,16 +253,16 @@

next_activity

- - - - - - - - - - + + + + + + + + + +
ParameterTypeRequiredDescription
session_indexstringyesREQUIRED. The 6-character session_index returned by start_session. The server resolves this index to a planning folder under .engineering/artifacts/planning/ and reads/writes session.json there. The index is stable across all tool calls in the session — there is no rotation discipline.
activity_idstringyesActivity ID to transition to. For the first call, use initialActivity from get_workflow. For subsequent calls, use an activity ID from the transitions field of the current activity.
transition_conditionstringnoThe transition condition that led to this activity (from the transitions field of the previous activity). Enables server-side validation of condition-activity consistency.
step_manifestobject[]noArray of completed-step entries from the previous activity, e.g. [{"step_id":"detect-review-mode","output":"is_review_mode=false"}]. Each entry has two string fields: step_id (the literal id from the activity's steps[] — note the field is step_id, not id) and output. output is a short summary of what the step produced; for a step with more than one declared output, report a JSON object keyed by output id, e.g. {"step_id":"resolve-reference","output":"{\"reference_path\":\"lib/x\",\"component_name\":\"x\"}"}. Omit the parameter entirely when no steps ran; do not pass an empty array or empty string.
step_manifest[].step_idstringyes-
step_manifest[].outputstringyes-
activity_manifestobject[]noActivity completion manifest from the orchestrator. Reports the sequence of activities completed so far with outcomes and transition conditions.
activity_manifest[].activity_idstringyes-
activity_manifest[].outcomestringyes-
activity_manifest[].transition_conditionstringno-
session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
activity_idstringyesActivity to move to. First call: use initialActivity from get_workflow. Later: use an id from transitions.
transition_conditionstringnoThe condition name that led to this transition, from the previous activity.
step_manifestobject[]noSteps completed in the previous activity, for example [{ "step_id": "detect-review-mode", "output": "is_review_mode=false" }]. Omit if no steps ran.
step_manifest[].step_idstringyesStep id from the activity definition (field name is step_id, not id).
step_manifest[].outputstringyesShort summary of what the step produced. Use a JSON object when the step has multiple outputs.
activity_manifestobject[]noHistory of completed activities with outcomes and transition conditions.
activity_manifest[].activity_idstringyesCompleted activity id.
activity_manifest[].outcomestringyesShort outcome summary for that activity.
activity_manifest[].transition_conditionstringnoCondition that led out of that activity, if any.
@@ -251,18 +270,21 @@

next_activity

get_activity

-

Load the complete activity definition for the current activity in the session.

+

Load the current activity definition, including steps and transitions.

Full description -

Load the complete activity definition for the current activity in the session. This is the worker's tool for retrieving the full activity details after the orchestrator has called next_activity to transition. Returns the complete activity definition including all steps, checkpoints, transitions to subsequent activities, rules, and technique references — everything needed to execute the activity. The activity is determined from the session state on disk, so no activity_id parameter is needed. context_tokens is REQUIRED — the worker declares its own context window; the server derives an eager step-technique bundling budget from it (availability headroom × a token→char factor, both server config) and inlines the activity's ungated step-bound techniques that fit, in document order, under that budget. When reference delivery is active (session context_mode "persistent" or bundle: "reference"), inherited techniques/rules content already delivered to this session+agent arrives as short { delivery: "unchanged", content_hash } markers instead of being repeated; bundle: "full" forces full delivery. Eligible ungated step-bound techniques are inlined corpus-wide under a step_techniques map (keyed by step id, each entry a discrete ▼ STEP block identical to a get_technique { step_id } fetch — engage those steps in order without refetching); gated steps and any technique that would overflow the derived budget (or a per-activity bundleTechniques.maxChars size cap; maxChars 0 opts the activity out) stay lazy and still require get_technique. Bundled deliveries are recorded as technique_bundled history events and count as fetch coverage for next_activity's manifest fidelity check.

+

Loads the full definition for whatever activity the session is currently on. No activity_id parameter — the server reads it from session state.

+

You must pass context_tokens: your worker's context window size in tokens. The server uses this to decide how many step techniques to bundle inline.

+

Ungated techniques that fit the budget are included in the response under step_techniques — the same content you would get from get_technique for that step. Gated steps and overflow techniques still need a separate get_technique call.

+

If the session uses persistent context mode (or you pass bundle: "reference"), content you already received may come back as short unchanged markers instead of full text. Pass bundle: "full" to force full delivery.

- - - + + +
ParameterTypeRequiredDescription
session_indexstringyesREQUIRED. The 6-character session_index returned by start_session. The server resolves this index to a planning folder under .engineering/artifacts/planning/ and reads/writes session.json there. The index is stable across all tool calls in the session — there is no rotation discipline.
context_tokensintegeryesREQUIRED. The calling worker's total context window in tokens. The server derives the eager step-technique bundling budget from this value (availability headroom × a token→char factor, both server config) and inlines the activity's ungated step-bound techniques that fit, in document order, under that budget; the remainder stay lazy via get_technique. Per-agent and per-call — never stored on the session, never defaulted. Omitting it is a validation error.
bundle"reference" | "full"noOptional delivery-mode override for the inherited techniques/rules bundle. "reference" replaces bundle content already delivered to this session+agent with short { delivery: "unchanged", content_hash } markers — only correct when THIS calling context received the earlier deliveries. "full" forces full delivery. Defaults from the session's context_mode ("persistent" → reference, otherwise full).
session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
context_tokensintegeryesYour worker context window in tokens. Required so the server can size inline technique bundling.
bundle"reference" | "full"noreference: return unchanged markers for content already delivered. full: always return complete text.
@@ -274,14 +296,15 @@

yield_checkpoint

Yield execution to the orchestrator at a checkpoint.

Full description -

Yield execution to the orchestrator at a checkpoint. Call this tool when you encounter a checkpoint step during activity execution. It records the checkpoint as active in the session state and returns the session_index, which the worker yields back to the orchestrator via a <checkpoint_yield> block.

+

Call when a checkpoint step tells you to stop and hand control to the orchestrator.

+

Records the checkpoint as active and returns the session_index for a <checkpoint_yield> block in your output.

- - + +
ParameterTypeRequiredDescription
session_indexstringyesREQUIRED. The 6-character session_index returned by start_session. The server resolves this index to a planning folder under .engineering/artifacts/planning/ and reads/writes session.json there. The index is stable across all tool calls in the session — there is no rotation discipline.
checkpoint_idstringyesThe ID of the checkpoint being yielded.
session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
checkpoint_idstringyesId of the checkpoint step you are yielding.
@@ -291,13 +314,14 @@

resume_checkpoint

Resume execution after the orchestrator resolves a checkpoint.

Full description -

Resume execution after the orchestrator resolves a checkpoint. Call this tool when the orchestrator resumes you with a checkpoint response. It verifies the checkpoint was resolved (no activeCheckpoint in state) and returns any variable updates you need to apply to your state.

+

Call after the orchestrator resolves a checkpoint and resumes you.

+

Verifies the checkpoint is cleared and returns any variable updates to apply before continuing the activity.

- +
ParameterTypeRequiredDescription
session_indexstringyesREQUIRED. The 6-character session_index returned by start_session. The server resolves this index to a planning folder under .engineering/artifacts/planning/ and reads/writes session.json there. The index is stable across all tool calls in the session — there is no rotation discipline.
session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
@@ -307,13 +331,14 @@

present_checkpoint

Load the full details of the currently-active checkpoint for the session.

Full description -

Load the full details of the currently-active checkpoint for the session. Returns the checkpoint definition including its message, user-facing options (with labels, descriptions, and effects like variable assignments), and any auto-advance configuration. Use this when you need to present a checkpoint interaction to the user based on a worker's yield. Reads the active checkpoint from state.activeCheckpoint — no separate checkpoint handle is needed.

+

Loads the active checkpoint's message, options, and effects so you can show it to the user.

+

Reads from state.activeCheckpoint — no separate checkpoint handle is needed.

- +
ParameterTypeRequiredDescription
session_indexstringyesREQUIRED. The 6-character session_index returned by start_session. The server resolves this index to a planning folder under .engineering/artifacts/planning/ and reads/writes session.json there. The index is stable across all tool calls in the session — there is no rotation discipline.
session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
@@ -323,16 +348,19 @@

respond_checkpoint

Submit a checkpoint response to clear the active-checkpoint gate.

Full description -

Submit a checkpoint response to clear the active-checkpoint gate. *MUST* present the checkpoint to the user and wait for their input. Exactly one of option_id, auto_advance, or condition_not_met must be provided. option_id: the user's selected option (works for all checkpoint types, enforces minimum response time). auto_advance: use the checkpoint's defaultOption (only for checkpoints with autoAdvanceMs; the server enforces the full timer). condition_not_met: dismiss a conditional checkpoint whose condition evaluated to false (only valid when the checkpoint has a condition field). setVariable effects are validated against the declared variable type, warn-only: mismatches are stored as written and surfaced in _meta.validation. Reads the active checkpoint from state.activeCheckpoint — no separate checkpoint handle is needed.

+

Submits the user's checkpoint decision and clears the active checkpoint.

+

Present the checkpoint to the user and wait for input before calling this.

+

Provide exactly one of: option_id (user picked an option), auto_advance (timer elapsed on a checkpoint with a default), or condition_not_met (conditional checkpoint whose condition was false).

+

Variable effects from the chosen option are applied; type mismatches produce warnings in _meta.validation but do not block the response.

- - - - + + + +
ParameterTypeRequiredDescription
session_indexstringyesREQUIRED. The 6-character session_index returned by start_session. The server resolves this index to a planning folder under .engineering/artifacts/planning/ and reads/writes session.json there. The index is stable across all tool calls in the session — there is no rotation discipline.
option_idstringnoThe option ID selected by the user. Must match one of the checkpoint's defined options.
auto_advancebooleannoSet to true to auto-advance a checkpoint using its defaultOption. Only valid for checkpoints with defaultOption and autoAdvanceMs. The server enforces the autoAdvanceMs timer. If you use auto_advance, present a message to the user that you are proceeding with the default option because no input was provided.
condition_not_metbooleannoSet to true to dismiss a conditional checkpoint whose condition was not met. Only valid for checkpoints that have a condition field.
session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
option_idstringnoOption the user selected. Must match one of the checkpoint's defined options.
auto_advancebooleannoSet true to use the checkpoint's default option after its timer elapses.
condition_not_metbooleannoSet true to dismiss a conditional checkpoint whose condition evaluated to false.
@@ -344,15 +372,19 @@

get_technique

Load a single composed technique within the current workflow or activity.

Full description -

Load a single composed technique within the current workflow or activity. If called before next_activity (no current activity), it loads the workflow's first declared technique. During an activity, it resolves the technique reference from the activity definition; with step_id, it loads the technique assigned to that step; without step_id, the activity's first declared technique. The returned technique is fully COMPOSED: it inherits its workflow-root techniques/TECHNIQUE.md base contract recursively — never the meta root for a non-meta workflow. Contract-inherited inputs/outputs are delivered under marked inherited_inputs/inherited_outputs blocks (each with a scope note) distinct from the technique's own inputs/outputs; rules are merged; ancestor Initial/Final protocol blocks wrap the descendant protocol and the server renumbers. A step-bound fetch also annotates the binding seam: each of the technique's own inputs carries a source: (step-binding value, workflow variable, prior step output, declared default, or UNRESOLVED — the latter also a warn-only validation warning), inherited entries carry one only where it adds to their scope note (step-binding override or a producer positioned later in the workflow), each remapped output carries a destination:, and a provenance_note states the output delivery mechanics. Annotations are static — resolved from declarations and document order — so payloads are deterministic per corpus and step. Techniques are loaded one at a time. In a session with context_mode "persistent", a refetch whose composed content is byte-identical to what this session+agent already received returns a short unchanged-reference ({ delivery: unchanged, content_hash }) instead of the full payload; pass full: true to force full content. Every fetch (either delivery path) is recorded in the session history as a technique_fetched event (resolved technique id, bound step_id when supplied, agent); next_activity's manifest validation reads these events and warns — advisory only — when a manifested technique step had no fetch during the activity.

+

Fetches one technique for the current workflow or activity.

+

Before any activity is active, returns the workflow's first technique. During an activity, use step_id to fetch a specific step's technique, or omit step_id for the activity's first technique.

+

The response is fully composed: inherited inputs/outputs and merged rules from ancestor techniques, plus binding annotations when fetched via a step.

+

Techniques load one at a time. In persistent context mode, an identical refetch may return a short unchanged marker; pass full: true to get the full payload again.

+

Every fetch is recorded for trace and advisory manifest checks on the next next_activity call.

- - - + + +
ParameterTypeRequiredDescription
session_indexstringyesREQUIRED. The 6-character session_index returned by start_session. The server resolves this index to a planning folder under .engineering/artifacts/planning/ and reads/writes session.json there. The index is stable across all tool calls in the session — there is no rotation discipline.
step_idstringnoOptional. Step ID within the current activity (e.g., "define-problem"). If omitted, returns the activity's first declared technique, or the workflow's first declared technique if no activity is active.
fullbooleannoOptional. Set true to force full content delivery even when the session's persistent context mode would answer a byte-identical refetch with an unchanged-reference. Use when your context no longer holds the earlier delivery (e.g. it was summarized away).
session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
step_idstringnoStep within the current activity. Omit to get the first technique for the activity or workflow.
fullbooleannoForce full technique content even when persistent mode would return an unchanged marker.
@@ -362,14 +394,17 @@

get_resource

Load a resource by its id, optionally narrowed to a single section.

Full description -

Load a resource by its id, optionally narrowed to a single section. Use this to fetch resources referenced in technique content (e.g. a template hyperlinked from an Input/Output). The resource_id is a text-only slug — bare (e.g., "review-mode") resolves within the session's workflow, or prefixed cross-workflow (e.g., "meta/bootstrap-protocol") resolves from the named workflow. Append a #section anchor (GitHub-style heading slug, e.g. "assumption-reconciliation#integration-with-assumptions-log") to return only that section and its body — used to fetch just the template a technique references without the whole file. Returns the resource content, id, and version. Each fetch is recorded in the session history as a resource_fetched event (observability only — no validation reads it).

+

Loads reference material by id — templates, guides, or other markdown resources linked from techniques.

+

Bare ids (review-mode) resolve within the current workflow. Prefixed ids (meta/bootstrap-protocol) load from another workflow.

+

Add #section to fetch one heading slice instead of the whole file.

+

Each fetch is logged for observability only; nothing validates that you called it.

- - + +
ParameterTypeRequiredDescription
session_indexstringyesREQUIRED. The 6-character session_index returned by start_session. The server resolves this index to a planning folder under .engineering/artifacts/planning/ and reads/writes session.json there. The index is stable across all tool calls in the session — there is no rotation discipline.
resource_idstringyesResource ref — bare slug ("review-mode"), cross-workflow prefixed ("meta/bootstrap-protocol"), each optionally suffixed with a "#section" heading anchor to return only that section (e.g. "assumption-reconciliation#integration-with-assumptions-log")
session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
resource_idstringyesResource slug, optionally workflow-prefixed (meta/bootstrap-protocol), optionally with #section anchor.
@@ -381,14 +416,15 @@

get_trace

Retrieve the execution trace for the current workflow session.

Full description -

Retrieve the execution trace for the current workflow session. Accepts an optional array of trace_tokens accumulated from next_activity _meta.trace_token responses to reconstruct a specific trace segment. If no trace_tokens are provided, returns the full in-memory trace for the current session (requires server-side tracing to be enabled). Use this for debugging, auditing, or reviewing the sequence of tool calls made during the session.

+

Returns the tool-call history for debugging or audit.

+

Pass accumulated trace_tokens from next_activity responses to reconstruct a specific segment. Omit them to read the live in-memory trace for the session.

- - + +
ParameterTypeRequiredDescription
session_indexstringyesREQUIRED. The 6-character session_index returned by start_session. The server resolves this index to a planning folder under .engineering/artifacts/planning/ and reads/writes session.json there. The index is stable across all tool calls in the session — there is no rotation discipline.
trace_tokensstring[]noAccumulated trace tokens from next_activity _meta.trace_token responses. If not provided, returns the full in-memory trace for the current session.
session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
trace_tokensstring[]noTokens collected from next_activity _meta.trace_token responses.
From 31be1a0b7c5570560faa9ed267b87af3ad1e6a03 Mon Sep 17 00:00:00 2001 From: Mike Clay Date: Sat, 11 Jul 2026 09:58:55 +0100 Subject: [PATCH 03/12] Remove baselines essay from quality-system page. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fold the one useful fact — only new binding-fidelity findings fail — into the guard table row instead of a separate history section. --- site/internals/quality-system.html | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/site/internals/quality-system.html b/site/internals/quality-system.html index 59d8ecd6..bff60f51 100644 --- a/site/internals/quality-system.html +++ b/site/internals/quality-system.html @@ -4,7 +4,7 @@ Quality system — Workflow Server - + @@ -103,7 +103,7 @@

The guard suite

validate-workflow-yaml, validate-activitiesEvery workflow manifest and activity file parses and satisfies the schemas — a dry run of the server's own loaders. check-all-refsEvery technique reference resolves to a real technique; no misspellings, no dangling paths. - check-binding-fidelityStep bindings are coherent end to end: arguments conform to declared inputs, reads resolve to a producer, outputs are consumed, and inputs have a source. + check-binding-fidelityStep bindings are coherent end to end: arguments conform to declared inputs, reads resolve to a producer, outputs are consumed, and inputs have a source. Only new findings fail — known ones are listed in binding-fidelity-baseline.json. check-identifier-qualificationTechnique input and output ids are qualified noun phrases (completion_summary, never a bare summary). check-technique-templateTechnique markdown follows the normative structure of the technique protocol. check-resource-anchorsEvery #section anchor a technique uses to reference a resource exists in that resource. @@ -113,9 +113,6 @@

The guard suite

-

Baselines: the ratchet

-

Guards that arrived after the corpus grew would have failed on hundreds of pre-existing findings, so those guards carry a checked-in baseline (for example binding-fidelity-baseline.json): known findings are tolerated, new ones fail the check, and burning down the baseline is ordinary, visible work. A guard whose baseline is empty — identifier qualification is one — has been ratcheted all the way: the rule now holds everywhere. The pattern turns "we should clean this up eventually" into a number that can only go down.

-

The test architecture

The Vitest suite (thirty-plus files) is organized around what could break:

    From 08d250ca7fa51f34f10627691b9f943785172878 Mon Sep 17 00:00:00 2001 From: Mike Clay Date: Sat, 11 Jul 2026 10:03:05 +0100 Subject: [PATCH 04/12] Add Workflow architecture guide with diagrams and site navigation. Introduce a dedicated guide page for workflows, activities, step kinds, techniques, resources, binding, and runtime delivery; wire it into the guide sequence and cross-link from Concepts and the home page. --- scripts/generate-site-data.ts | 3 +- site/api/protocol.html | 1 + site/api/schemas.html | 1 + site/api/tools.html | 1 + site/design/rationale.html | 1 + site/guide/concepts.html | 48 +--- site/guide/getting-started.html | 1 + site/guide/ide-setup.html | 1 + site/guide/running-workflows.html | 3 +- site/guide/workflow-architecture.html | 303 ++++++++++++++++++++++++++ site/index.html | 5 +- site/internals/quality-system.html | 1 + site/internals/request-lifecycle.html | 1 + site/internals/server-anatomy.html | 1 + site/internals/session-store.html | 1 + site/specs/architecture.html | 1 + site/specs/artifact-management.html | 1 + site/specs/checkpoints.html | 1 + site/specs/dispatch.html | 1 + site/specs/resource-resolution.html | 1 + site/specs/state-management.html | 1 + site/specs/workflow-fidelity.html | 1 + 22 files changed, 333 insertions(+), 46 deletions(-) create mode 100644 site/guide/workflow-architecture.html diff --git a/scripts/generate-site-data.ts b/scripts/generate-site-data.ts index a8efb70e..de442b0f 100644 --- a/scripts/generate-site-data.ts +++ b/scripts/generate-site-data.ts @@ -42,7 +42,8 @@ export const SITE_ROUTES: SiteRoute[] = [ { relPath: 'guide/getting-started.html', section: 'guide', title: 'Getting started', navLabel: 'Getting started', sequence: 1 }, { relPath: 'guide/ide-setup.html', section: 'guide', title: 'IDE setup', navLabel: 'IDE setup', sequence: 2 }, { relPath: 'guide/concepts.html', section: 'guide', title: 'Concepts', navLabel: 'Concepts', sequence: 3 }, - { relPath: 'guide/running-workflows.html', section: 'guide', title: 'Running workflows', navLabel: 'Running workflows', sequence: 4 }, + { relPath: 'guide/workflow-architecture.html', section: 'guide', title: 'Workflow architecture', navLabel: 'Workflow architecture', sequence: 4 }, + { relPath: 'guide/running-workflows.html', section: 'guide', title: 'Running workflows', navLabel: 'Running workflows', sequence: 5 }, { relPath: 'specs/architecture.html', section: 'specs', title: 'Architecture overview', navLabel: 'Overview', sequence: 0, breadcrumbLabel: 'Architecture' }, { relPath: 'specs/dispatch.html', section: 'specs', title: 'Hierarchical dispatch', navLabel: 'Dispatch', sequence: 1, parent: 'specs/architecture.html', breadcrumbLabel: 'Dispatch' }, { relPath: 'specs/checkpoints.html', section: 'specs', title: 'Just-in-time checkpoints', navLabel: 'Checkpoints', sequence: 2, parent: 'specs/architecture.html', breadcrumbLabel: 'Checkpoints' }, diff --git a/site/api/protocol.html b/site/api/protocol.html index 413b1a87..a6d03254 100644 --- a/site/api/protocol.html +++ b/site/api/protocol.html @@ -24,6 +24,7 @@
  • Getting started
  • IDE setup
  • Concepts
    • +
  • Workflow architecture
  • Running workflows
diff --git a/site/api/schemas.html b/site/api/schemas.html index f53d9e8f..33df2394 100644 --- a/site/api/schemas.html +++ b/site/api/schemas.html @@ -24,6 +24,7 @@
  • Getting started
  • IDE setup
  • Concepts
    • +
  • Workflow architecture
  • Running workflows
    • diff --git a/site/api/tools.html b/site/api/tools.html index a370d602..0b2164c2 100644 --- a/site/api/tools.html +++ b/site/api/tools.html @@ -24,6 +24,7 @@
  • Getting started
  • IDE setup
  • Concepts
    • +
  • Workflow architecture
  • Running workflows
    • diff --git a/site/design/rationale.html b/site/design/rationale.html index a3876399..c1768e27 100644 --- a/site/design/rationale.html +++ b/site/design/rationale.html @@ -24,6 +24,7 @@
  • Getting started
  • IDE setup
  • Concepts
    • +
  • Workflow architecture
  • Running workflows
    • diff --git a/site/guide/concepts.html b/site/guide/concepts.html index 91c5c966..b7e77d05 100644 --- a/site/guide/concepts.html +++ b/site/guide/concepts.html @@ -24,6 +24,7 @@
  • Getting started
  • IDE setup
  • Concepts
    • +
  • Workflow architecture
  • Running workflows
    • @@ -90,7 +91,7 @@

    Concepts

    -

    Five ideas explain the system: workflows, activities, techniques, sessions, and checkpoints. The model diagram on the home page shows how they chain from a user goal down to tool calls.

    +

    Five ideas explain the system: workflows, activities, techniques, sessions, and checkpoints. The model diagram on the home page shows how they chain from a user goal down to tool calls. For file layout, step kinds, and binding, see Workflow architecture.

    Terms at a glance

    @@ -107,44 +108,7 @@

    Terms at a glance

    What a workflow is made of

    -

    A workflow is a directory of declarative files, not code. The manifest names the workflow and its variables; each activity file defines one phase as an ordered list of steps; techniques are markdown documents describing a capability; and resources are reference material a technique can pull in when needed.

    - -
    - - Anatomy of a workflow directory - A workflow manifest lists activities. Each activity file contains ordered steps of four kinds: technique, action, checkpoint, and loop. Steps reference technique documents, which can reference resources. - - - - - - - - workflow.yaml - manifest: variables, rules - - activities/*.yaml - ordered steps, transitions - - techniques/*.md - how to do one capability - - resources/*.md - reference, lazy-loaded - - - - - - - - lists - bind - links - - -
    Anatomy of a workflow directory. The manifest lists activities; activity steps come in four kinds (technique, action, checkpoint, loop) and bind techniques; techniques reference resources that load only when needed. The exact file shapes are in the schema reference.
    -
    +

    A workflow is a directory of declarative files — manifest, activities, techniques, and resources — not executable code. Workflow architecture walks through each piece with diagrams: what lives on disk, the four step kinds, how techniques compose, and what the server delivers at runtime.

    Sessions

    A session is one run of a workflow. When the agent calls start_session, the server creates (or resumes) a planning folder under your project's .engineering/artifacts/planning/ and writes a session.json there — the canonical record of which activity is current, which variables are set, and whether a checkpoint is active. The tool returns a short session_index token that identifies the session on every later call.

    @@ -201,21 +165,21 @@

    Checkpoints — where you stay in control

    Your choice can set workflow variables — picking "skip the audit" or "include migration" changes which activities and steps run afterwards. Some checkpoints define a default option and can auto-advance after a timeout; the server still enforces the timer.

    Techniques and resources

    -

    A technique is a markdown document that tells the agent how to perform one capability — its inputs, its protocol, its outputs. Steps bind techniques by reference, and the agent fetches each one just-in-time with get_technique as it reaches the step, rather than receiving everything up front. When a technique points at longer reference material, the agent pulls it with get_resource only if it actually needs it. This progressive disclosure keeps the agent's context small and focused on the current step.

    +

    A technique is a markdown document that tells the agent how to perform one capability. Steps bind techniques by reference; the agent fetches each one just-in-time with get_technique as it reaches the step. Resources load with get_resource only when needed. See Workflow architecture for paths, composition, and binding.

    Fidelity: why agents stay on script

    The server enforces the workflow instead of trusting the agent to follow it. Transitions are validated, checkpoints gate advancement, and session state on disk is the single source of truth.

    Read workflow fidelity for what each layer protects against, and architecture overview for the six models behind it.

    Next

    -

    Run your first workflow - what to say to the agent and what happens underneath.

    +

    Workflow architecture — file layout, step kinds, binding, and runtime delivery. Then run your first workflow.

    diff --git a/site/guide/getting-started.html b/site/guide/getting-started.html index b8f7dcf3..218b4f28 100644 --- a/site/guide/getting-started.html +++ b/site/guide/getting-started.html @@ -24,6 +24,7 @@
  • Getting started
  • IDE setup
  • Concepts
    • +
  • Workflow architecture
  • Running workflows
    • diff --git a/site/guide/ide-setup.html b/site/guide/ide-setup.html index ca336015..916ae245 100644 --- a/site/guide/ide-setup.html +++ b/site/guide/ide-setup.html @@ -24,6 +24,7 @@
  • Getting started
  • IDE setup
  • Concepts
    • +
  • Workflow architecture
  • Running workflows
    • diff --git a/site/guide/running-workflows.html b/site/guide/running-workflows.html index 7dc0d4e7..22a420b0 100644 --- a/site/guide/running-workflows.html +++ b/site/guide/running-workflows.html @@ -24,6 +24,7 @@
  • Getting started
  • IDE setup
  • Concepts
    • +
  • Workflow architecture
  • Running workflows
    • @@ -156,7 +157,7 @@

    Next

    diff --git a/site/guide/workflow-architecture.html b/site/guide/workflow-architecture.html new file mode 100644 index 00000000..f59baefc --- /dev/null +++ b/site/guide/workflow-architecture.html @@ -0,0 +1,303 @@ + + + + + +Workflow architecture — Workflow Server + + + + + + +
    +
    + Workflow Server + + + +
    +
    + + + + + + +
    +

    Workflow architecture

    +

    Workflows are declarative files, not code. This page explains what each file type means, how the pieces connect, and what the server delivers to the agent as work progresses.

    +

    For runtime behaviour (checkpoints, dispatch, fidelity), see server architecture. For file shapes, see the schema reference.

    + + + +

    Overview

    +

    Think in two layers. On disk, a workflow is a folder of YAML and markdown. At runtime, the agent asks the server for one piece at a time so its context stays focused on the current step.

    + +
    + + Content model on disk + A workflow directory contains a manifest, activity files, technique markdown files, and resource markdown files. Activities list ordered steps; technique steps point at techniques; techniques link to resources. + + + + + + + + workflow.yaml + manifest + + activities/*.yaml + phases + steps + + techniques/*.md + capabilities + + resources/*.md + reference + + + + + + + + lists + bind + refs + + Everything under workflows/<workflow-id>/ in the workflows branch + +
    The workflow directory layout. The manifest names the workflow and lists activities; each activity file is an ordered step list; technique steps resolve markdown capability files; techniques may link to resources that load only when needed.
    +
    + +

    Workflows

    +

    A workflow is the top-level process — for example work-package for planning and implementing a unit of work. Its manifest (workflow.yaml) declares:

    +
      +
    • Identity — id, name, version
      • +
    • Variables — named slots in session state (with optional defaults seeded at session start)
      • +
    • Activities — the phases the orchestrator can move between
      • +
    • Initial activity — where a new session begins (returned by get_workflow as initialActivity)
      • +
    • Rules and orchestrator techniques — behaviour bundled into the first get_workflow response
      • +
    +

    Workflows do not contain executable code. They describe structure; the agent interprets steps and the server enforces transitions, checkpoints, and session state.

    + +

    Activities

    +

    An activity is one phase inside a workflow — for example Plan & Prepare or Validate & Commit. Each activity file defines:

    +
      +
    • An ordered steps[] list the worker executes top to bottom (with loops branching locally)
      • +
    • transitions — which activity comes next, often gated by workflow variables
      • +
    • Optional activity-level techniques[] refs the server may bundle into get_activity
      • +
    +

    Only one activity is current in a session at a time. The orchestrator advances with next_activity; the worker loads the new activity with get_activity.

    + +

    Step kinds

    +

    Every step has a kind. Four kinds appear in activity files today:

    + +
    + + The four step kinds + Four boxes for technique, action, checkpoint, and loop steps, showing what each one does at a high level. + + + kind: technique + bind a capability; + fetch via get_technique + + kind: action + inline instructions + validate, message, … + + kind: checkpoint + pause for user + decision; see Concepts + + kind: loop + repeat nested steps + while a condition holds + + Steps run in file order unless a loop or transition sends execution elsewhere + +
    The four step kinds. Technique steps delegate to markdown capability definitions; action steps are short agent-interpreted instructions; checkpoint steps gate progress on a user decision; loop steps repeat a nested block.
    +
    + +
    + + + + + + + + +
    KindWhat it isAgent behaviour
    techniqueReference to a capability by :: path, with optional input bindingsCall get_technique for the step (or use content already bundled in get_activity), follow the protocol, record outputs
    actionOne or more inline actions (validate, message, …)Execute the listed actions against current variables; the server does not interpret action verbs
    checkpointA declared pause with options and effectsCall yield_checkpoint; orchestrator presents and respond_checkpoint; worker resume_checkpoint — see checkpoints in Concepts
    loopA nested step list with an exit conditionRepeat the nested steps until the condition is satisfied or the loop declares completion
    +
    + +

    Techniques

    +

    A technique is a markdown file that describes one capability: what it does, what inputs it needs, what outputs it produces, the ordered protocol to follow, and any rules to obey.

    +

    Techniques are addressed with :: paths. A bare name like plan resolves in the current workflow first, then falls back to the shared meta workflow. Paths can nest: review-assumptions::collect is a sub-technique under review-assumptions.

    +

    When the server delivers a technique, it composes it: inherited inputs/outputs and merged rules from ancestor techniques, plus binding annotations that show where each input value comes from and where each output goes. The normative file anatomy is in the technique protocol specification (source).

    + +

    Resources

    +

    A resource is reference material — templates, long guides, tables — stored as markdown under resources/. Techniques link to resources instead of inlining them.

    +

    The agent fetches a resource with get_resource only when the technique it is executing needs it. You can request a single section with a #heading-anchor suffix. Resolution rules (bare slug vs meta/bootstrap-protocol cross-workflow refs) are documented on the resolution model page.

    + +

    Variables and binding

    +

    Workflow variables live in session.json. The server seeds defaults when a session or child workflow starts. Checkpoint options and some step outputs update them as work proceeds.

    +

    When a technique step runs, each declared input is bound from a source the server can see statically: a workflow variable, a value passed on the step, a prior step's output, or a declared default. Each output is mapped to a destination (often a variable or a later step's input). If a binding cannot be resolved, the server surfaces it in the delivered technique so the agent knows what is missing.

    +

    Activity transitions read the same variable bag: the orchestrator picks the next activity by evaluating transition conditions against current state.

    + +

    Runtime delivery

    +

    The agent does not read workflow files from disk. It calls MCP tools; the server loads definitions and returns only what the current step needs.

    + +
    + + Typical tool sequence + A left-to-right sequence of MCP tool calls from start_session through get_workflow, next_activity, get_activity, get_technique, and optional get_resource. + + + + + + + + start_session + session_index + + get_workflow + initialActivity + + next_activity + advance state + + get_activity + steps + bundle + + get_technique + per step + + get_resource + when linked + + + + + + + + + + Orchestrator calls next_activity; worker calls get_activity and get_technique + Repeat the next_activity → get_activity → get_technique loop for each activity + Checkpoint tools interrupt the loop wherever a checkpoint step appears + + +
    Typical delivery sequence. After start_session, the orchestrator loads workflow metadata, advances with next_activity, and the worker loads each activity and its techniques. Resources load on demand. Full call ordering is in the protocol guide.
    +
    + +

    get_activity may inline some step techniques up front (based on context_tokens and bundling limits) so the worker can start without an immediate get_technique per step. Gated or oversized techniques still fetch lazily.

    + +

    Normative references

    + + +

    Next

    +

    Concepts covers sessions and checkpoints from a user perspective. Running workflows shows what to say to the agent in practice.

    +
    + + + + + + + + + + diff --git a/site/index.html b/site/index.html index 8145760b..d957e791 100644 --- a/site/index.html +++ b/site/index.html @@ -24,6 +24,7 @@
  • Getting started
  • IDE setup
  • Concepts
    • +
  • Workflow architecture
  • Running workflows
    • @@ -151,7 +152,7 @@

    Run work in your IDE

    Understand the system

    Learn how it works

    Core concepts, architecture models, API reference, and design rationale.

    - Concepts · Architecture · Tools + Concepts · Workflow architecture · Architecture · Tools

  • Contribute

    @@ -160,7 +161,7 @@

    Work on the server

    Server anatomy · Quality system · Development guide
    • -

    Recommended guide order: Getting started → IDE setup → Concepts → Running workflows.

    +

    Recommended guide order: Getting started → IDE setup → Concepts → Workflow architecture → Running workflows.

    diff --git a/site/internals/quality-system.html b/site/internals/quality-system.html index bff60f51..51c81b76 100644 --- a/site/internals/quality-system.html +++ b/site/internals/quality-system.html @@ -24,6 +24,7 @@
  • Getting started
  • IDE setup
  • Concepts
    • +
  • Workflow architecture
  • Running workflows
    • diff --git a/site/internals/request-lifecycle.html b/site/internals/request-lifecycle.html index 950dbe0b..75065140 100644 --- a/site/internals/request-lifecycle.html +++ b/site/internals/request-lifecycle.html @@ -24,6 +24,7 @@
  • Getting started
  • IDE setup
  • Concepts
    • +
  • Workflow architecture
  • Running workflows
    • diff --git a/site/internals/server-anatomy.html b/site/internals/server-anatomy.html index fbd09697..d1f54b60 100644 --- a/site/internals/server-anatomy.html +++ b/site/internals/server-anatomy.html @@ -24,6 +24,7 @@
  • Getting started
  • IDE setup
  • Concepts
    • +
  • Workflow architecture
  • Running workflows
    • diff --git a/site/internals/session-store.html b/site/internals/session-store.html index c593a650..5f7f4a81 100644 --- a/site/internals/session-store.html +++ b/site/internals/session-store.html @@ -24,6 +24,7 @@
  • Getting started
  • IDE setup
  • Concepts
    • +
  • Workflow architecture
  • Running workflows
    • diff --git a/site/specs/architecture.html b/site/specs/architecture.html index a48b6cd0..6aa511ee 100644 --- a/site/specs/architecture.html +++ b/site/specs/architecture.html @@ -24,6 +24,7 @@
  • Getting started
  • IDE setup
  • Concepts
    • +
  • Workflow architecture
  • Running workflows
    • diff --git a/site/specs/artifact-management.html b/site/specs/artifact-management.html index ddf0b149..451878d3 100644 --- a/site/specs/artifact-management.html +++ b/site/specs/artifact-management.html @@ -24,6 +24,7 @@
  • Getting started
  • IDE setup
  • Concepts
    • +
  • Workflow architecture
  • Running workflows
    • diff --git a/site/specs/checkpoints.html b/site/specs/checkpoints.html index a5638590..6d03a3d4 100644 --- a/site/specs/checkpoints.html +++ b/site/specs/checkpoints.html @@ -24,6 +24,7 @@
  • Getting started
  • IDE setup
  • Concepts
    • +
  • Workflow architecture
  • Running workflows
    • diff --git a/site/specs/dispatch.html b/site/specs/dispatch.html index 6a8a9592..1921cc96 100644 --- a/site/specs/dispatch.html +++ b/site/specs/dispatch.html @@ -24,6 +24,7 @@
  • Getting started
  • IDE setup
  • Concepts
    • +
  • Workflow architecture
  • Running workflows
    • diff --git a/site/specs/resource-resolution.html b/site/specs/resource-resolution.html index 2621ea4d..5edce82f 100644 --- a/site/specs/resource-resolution.html +++ b/site/specs/resource-resolution.html @@ -24,6 +24,7 @@
  • Getting started
  • IDE setup
  • Concepts
    • +
  • Workflow architecture
  • Running workflows
    • diff --git a/site/specs/state-management.html b/site/specs/state-management.html index da9f85b1..e8a02c3e 100644 --- a/site/specs/state-management.html +++ b/site/specs/state-management.html @@ -24,6 +24,7 @@
  • Getting started
  • IDE setup
  • Concepts
    • +
  • Workflow architecture
  • Running workflows
    • diff --git a/site/specs/workflow-fidelity.html b/site/specs/workflow-fidelity.html index 525e60da..a5ba359f 100644 --- a/site/specs/workflow-fidelity.html +++ b/site/specs/workflow-fidelity.html @@ -24,6 +24,7 @@
  • Getting started
  • IDE setup
  • Concepts
    • +
  • Workflow architecture
  • Running workflows
    • From 5a4c46879844dc15e4f1fcff18128fc022cac6e7 Mon Sep 17 00:00:00 2001 From: Mike Clay Date: Sat, 11 Jul 2026 10:11:08 +0100 Subject: [PATCH 05/12] Add section diagrams to Workflow architecture guide. Illustrate workflow manifest contents, activity step/transition structure, and technique file anatomy with resolution and composition. --- site/guide/workflow-architecture.html | 148 ++++++++++++++++++++++++++ 1 file changed, 148 insertions(+) diff --git a/site/guide/workflow-architecture.html b/site/guide/workflow-architecture.html index f59baefc..cd7f8813 100644 --- a/site/guide/workflow-architecture.html +++ b/site/guide/workflow-architecture.html @@ -159,6 +159,60 @@

    Workflows

    Workflows do not contain executable code. They describe structure; the agent interprets steps and the server enforces transitions, checkpoints, and session state.

    +
    + + Inside a workflow manifest + A workflow.yaml manifest connects to variables, a list of activities, rules, and orchestrator techniques. Activities form a sequence the orchestrator moves through; one is marked as the initial activity. + + + + + + + + workflow.yaml + id · name · version + + variables[] + session state slots + + activities[] + phase definitions + + rules + workflow + activity + + techniques[] + orchestrator bundle + + + + + + + + + + + + + + start-wp + initial + + plan-prepare + + implement + + validate + + complete + + Example path from work-package — transitions pick the next box + +
    What lives in the workflow manifest. Variables and rules apply across the whole run; the activity list is the phase graph the orchestrator walks; initialActivity names the first phase (here, start-wp).
    +
    +

    Activities

    An activity is one phase inside a workflow — for example Plan & Prepare or Validate & Commit. Each activity file defines:

      @@ -168,6 +222,46 @@

      Activities

    Only one activity is current in a session at a time. The orchestrator advances with next_activity; the worker loads the new activity with get_activity.

    +
    + + Inside an activity file + An activity YAML file contains an ordered steps list executed top to bottom, then transitions that choose the next activity based on conditions. + + + + + + + + activities/plan-prepare.yaml + id · name · steps[] · transitions + + action — env-prerequisites + + technique — create-plan + + technique — collect-assumptions + + loop — assumption rounds + + transition + when ready → assumptions-review + + transition + else → strategic-review + + + + + + + + worker runs steps top → bottom; orchestrator reads transitions after the activity completes + + +
    An activity file in practice. The worker executes steps[] in order; when the activity finishes, the orchestrator evaluates transitions against workflow variables to choose the next activity.
    +
    +

    Step kinds

    Every step has a kind. Four kinds appear in activity files today:

    @@ -215,6 +309,60 @@

    Techniques

    Techniques are addressed with :: paths. A bare name like plan resolves in the current workflow first, then falls back to the shared meta workflow. Paths can nest: review-assumptions::collect is a sub-technique under review-assumptions.

    When the server delivers a technique, it composes it: inherited inputs/outputs and merged rules from ancestor techniques, plus binding annotations that show where each input value comes from and where each output goes. The normative file anatomy is in the technique protocol specification (source).

    +
    + + Technique file and resolution + A technique markdown file has Capability, Inputs, Outputs, Protocol, and Rules sections. A reference resolves in the current workflow first, then falls back to meta. Delivery composes ancestor contracts around the requested technique. + + + + + + + + techniques/plan.md + + Capability + + Inputs + + Outputs + + Protocol + + Rules + + plan + step technique ref + + current workflow + workflows/<wf>/techniques/ + + meta fallback + workflows/meta/techniques/ + + composed delivery + ancestor Initial/Final + inherited I/O + rules + binding source/dest + step protocol body + + + + + + + + + 1. look here + 2. if missing + Nested refs use subfolders + review-assumptions::collect + + +
    Technique anatomy and resolution. The markdown sections are what the agent follows; the server resolves the path workflow-first, then composes ancestor contracts and binding annotations into the wire payload.
    +
    +

    Resources

    A resource is reference material — templates, long guides, tables — stored as markdown under resources/. Techniques link to resources instead of inlining them.

    The agent fetches a resource with get_resource only when the technique it is executing needs it. You can request a single section with a #heading-anchor suffix. Resolution rules (bare slug vs meta/bootstrap-protocol cross-workflow refs) are documented on the resolution model page.

    From fdcaef1e11b754bb3a66b82e8622bc38c67c944a Mon Sep 17 00:00:00 2001 From: Mike Clay Date: Sat, 11 Jul 2026 10:12:48 +0100 Subject: [PATCH 06/12] =?UTF-8?q?Move=20workflow=20architecture=20page=20u?= =?UTF-8?q?nder=20Architecture=20=E2=86=92=20Workflows.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Relocate to specs/workflows.html in the top-bar Architecture section, update cross-links, and restore the guide sequence to four pages. --- scripts/generate-site-data.ts | 16 +++---- site/api/protocol.html | 2 +- site/api/schemas.html | 2 +- site/api/tools.html | 2 +- site/design/rationale.html | 2 +- site/guide/concepts.html | 12 +++--- site/guide/getting-started.html | 2 +- site/guide/ide-setup.html | 2 +- site/guide/running-workflows.html | 4 +- site/index.html | 6 +-- site/internals/quality-system.html | 2 +- site/internals/request-lifecycle.html | 2 +- site/internals/server-anatomy.html | 2 +- site/internals/session-store.html | 2 +- site/specs/architecture.html | 3 +- site/specs/artifact-management.html | 2 +- site/specs/checkpoints.html | 2 +- site/specs/dispatch.html | 4 +- site/specs/resource-resolution.html | 2 +- site/specs/state-management.html | 2 +- site/specs/workflow-fidelity.html | 2 +- .../workflows.html} | 42 +++++++++---------- 22 files changed, 59 insertions(+), 58 deletions(-) rename site/{guide/workflow-architecture.html => specs/workflows.html} (95%) diff --git a/scripts/generate-site-data.ts b/scripts/generate-site-data.ts index de442b0f..381e71e4 100644 --- a/scripts/generate-site-data.ts +++ b/scripts/generate-site-data.ts @@ -42,15 +42,15 @@ export const SITE_ROUTES: SiteRoute[] = [ { relPath: 'guide/getting-started.html', section: 'guide', title: 'Getting started', navLabel: 'Getting started', sequence: 1 }, { relPath: 'guide/ide-setup.html', section: 'guide', title: 'IDE setup', navLabel: 'IDE setup', sequence: 2 }, { relPath: 'guide/concepts.html', section: 'guide', title: 'Concepts', navLabel: 'Concepts', sequence: 3 }, - { relPath: 'guide/workflow-architecture.html', section: 'guide', title: 'Workflow architecture', navLabel: 'Workflow architecture', sequence: 4 }, - { relPath: 'guide/running-workflows.html', section: 'guide', title: 'Running workflows', navLabel: 'Running workflows', sequence: 5 }, + { relPath: 'guide/running-workflows.html', section: 'guide', title: 'Running workflows', navLabel: 'Running workflows', sequence: 4 }, { relPath: 'specs/architecture.html', section: 'specs', title: 'Architecture overview', navLabel: 'Overview', sequence: 0, breadcrumbLabel: 'Architecture' }, - { relPath: 'specs/dispatch.html', section: 'specs', title: 'Hierarchical dispatch', navLabel: 'Dispatch', sequence: 1, parent: 'specs/architecture.html', breadcrumbLabel: 'Dispatch' }, - { relPath: 'specs/checkpoints.html', section: 'specs', title: 'Just-in-time checkpoints', navLabel: 'Checkpoints', sequence: 2, parent: 'specs/architecture.html', breadcrumbLabel: 'Checkpoints' }, - { relPath: 'specs/state-management.html', section: 'specs', title: 'State management', navLabel: 'State', sequence: 3, parent: 'specs/architecture.html', breadcrumbLabel: 'State' }, - { relPath: 'specs/artifact-management.html', section: 'specs', title: 'Artifact management', navLabel: 'Artifacts', sequence: 4, parent: 'specs/architecture.html', breadcrumbLabel: 'Artifacts' }, - { relPath: 'specs/resource-resolution.html', section: 'specs', title: 'Resource resolution', navLabel: 'Resolution', sequence: 5, parent: 'specs/architecture.html', breadcrumbLabel: 'Resolution' }, - { relPath: 'specs/workflow-fidelity.html', section: 'specs', title: 'Workflow fidelity', navLabel: 'Fidelity', sequence: 6, parent: 'specs/architecture.html', breadcrumbLabel: 'Fidelity' }, + { relPath: 'specs/workflows.html', section: 'specs', title: 'Workflow architecture', navLabel: 'Workflows', sequence: 1, parent: 'specs/architecture.html', breadcrumbLabel: 'Workflows' }, + { relPath: 'specs/dispatch.html', section: 'specs', title: 'Hierarchical dispatch', navLabel: 'Dispatch', sequence: 2, parent: 'specs/architecture.html', breadcrumbLabel: 'Dispatch' }, + { relPath: 'specs/checkpoints.html', section: 'specs', title: 'Just-in-time checkpoints', navLabel: 'Checkpoints', sequence: 3, parent: 'specs/architecture.html', breadcrumbLabel: 'Checkpoints' }, + { relPath: 'specs/state-management.html', section: 'specs', title: 'State management', navLabel: 'State', sequence: 4, parent: 'specs/architecture.html', breadcrumbLabel: 'State' }, + { relPath: 'specs/artifact-management.html', section: 'specs', title: 'Artifact management', navLabel: 'Artifacts', sequence: 5, parent: 'specs/architecture.html', breadcrumbLabel: 'Artifacts' }, + { relPath: 'specs/resource-resolution.html', section: 'specs', title: 'Resource resolution', navLabel: 'Resolution', sequence: 6, parent: 'specs/architecture.html', breadcrumbLabel: 'Resolution' }, + { relPath: 'specs/workflow-fidelity.html', section: 'specs', title: 'Workflow fidelity', navLabel: 'Fidelity', sequence: 7, parent: 'specs/architecture.html', breadcrumbLabel: 'Fidelity' }, { relPath: 'api/tools.html', section: 'api', title: 'MCP tool reference', navLabel: 'Tools', sequence: 1 }, { relPath: 'api/schemas.html', section: 'api', title: 'Schema reference', navLabel: 'Schemas', sequence: 2 }, { relPath: 'api/protocol.html', section: 'api', title: 'Protocol in practice', navLabel: 'Protocol guide', sequence: 3 }, diff --git a/site/api/protocol.html b/site/api/protocol.html index a6d03254..8c11924f 100644 --- a/site/api/protocol.html +++ b/site/api/protocol.html @@ -24,7 +24,6 @@
  • Getting started
  • IDE setup
  • Concepts
    • -
  • Workflow architecture
  • Running workflows
    • @@ -34,6 +33,7 @@ Architecture @@ -34,6 +33,7 @@ Architecture @@ -34,6 +33,7 @@ Architecture @@ -34,6 +33,7 @@ Architecture @@ -34,6 +33,7 @@ Architecture
    • Overview
      • +
    • Workflows
    • Dispatch
    • Checkpoints
    • State
      • @@ -91,7 +91,7 @@

      Concepts

      -

      Five ideas explain the system: workflows, activities, techniques, sessions, and checkpoints. The model diagram on the home page shows how they chain from a user goal down to tool calls. For file layout, step kinds, and binding, see Workflow architecture.

      +

      Five ideas explain the system: workflows, activities, techniques, sessions, and checkpoints. The model diagram on the home page shows how they chain from a user goal down to tool calls. For file layout, step kinds, and binding, see Workflows under Architecture.

      Terms at a glance

      @@ -108,7 +108,7 @@

      Terms at a glance

      What a workflow is made of

      -

      A workflow is a directory of declarative files — manifest, activities, techniques, and resources — not executable code. Workflow architecture walks through each piece with diagrams: what lives on disk, the four step kinds, how techniques compose, and what the server delivers at runtime.

      +

      A workflow is a directory of declarative files — manifest, activities, techniques, and resources — not executable code. Workflows walks through each piece with diagrams: what lives on disk, the four step kinds, how techniques compose, and what the server delivers at runtime.

      Sessions

      A session is one run of a workflow. When the agent calls start_session, the server creates (or resumes) a planning folder under your project's .engineering/artifacts/planning/ and writes a session.json there — the canonical record of which activity is current, which variables are set, and whether a checkpoint is active. The tool returns a short session_index token that identifies the session on every later call.

      @@ -165,21 +165,21 @@

      Checkpoints — where you stay in control

      Your choice can set workflow variables — picking "skip the audit" or "include migration" changes which activities and steps run afterwards. Some checkpoints define a default option and can auto-advance after a timeout; the server still enforces the timer.

      Techniques and resources

      -

      A technique is a markdown document that tells the agent how to perform one capability. Steps bind techniques by reference; the agent fetches each one just-in-time with get_technique as it reaches the step. Resources load with get_resource only when needed. See Workflow architecture for paths, composition, and binding.

      +

      A technique is a markdown document that tells the agent how to perform one capability. Steps bind techniques by reference; the agent fetches each one just-in-time with get_technique as it reaches the step. Resources load with get_resource only when needed. See Workflows for paths, composition, and binding.

      Fidelity: why agents stay on script

      The server enforces the workflow instead of trusting the agent to follow it. Transitions are validated, checkpoints gate advancement, and session state on disk is the single source of truth.

      Read workflow fidelity for what each layer protects against, and architecture overview for the six models behind it.

      Next

      -

      Workflow architecture — file layout, step kinds, binding, and runtime delivery. Then run your first workflow.

      +

      Workflows — file layout, step kinds, binding, and runtime delivery. Then run your first workflow.

      diff --git a/site/guide/getting-started.html b/site/guide/getting-started.html index 218b4f28..616ff92e 100644 --- a/site/guide/getting-started.html +++ b/site/guide/getting-started.html @@ -24,7 +24,6 @@
    • Getting started
    • IDE setup
    • Concepts
      • -
    • Workflow architecture
    • Running workflows
    @@ -34,6 +33,7 @@ Architecture @@ -34,6 +33,7 @@ Architecture @@ -34,6 +33,7 @@ Architecture @@ -34,6 +33,7 @@ Architecture -

    Recommended guide order: Getting started → IDE setup → Concepts → Workflow architecture → Running workflows.

    +

    Recommended guide order: Getting started → IDE setup → Concepts → Running workflows. For workflow file structure, see Architecture → Workflows.

    diff --git a/site/internals/quality-system.html b/site/internals/quality-system.html index 51c81b76..13871c85 100644 --- a/site/internals/quality-system.html +++ b/site/internals/quality-system.html @@ -24,7 +24,6 @@
  • Getting started
  • IDE setup
  • Concepts
    • -
  • Workflow architecture
  • Running workflows
    • @@ -34,6 +33,7 @@ Architecture @@ -34,6 +33,7 @@ Architecture @@ -34,6 +33,7 @@ Architecture @@ -34,6 +33,7 @@ Architecture @@ -34,6 +33,7 @@ Architecture
    • Overview
      • +
    • Workflows
    • Dispatch
    • Checkpoints
    • State
      • @@ -92,6 +92,7 @@

      Architecture

      A small state machine wrapped in an MCP tool surface: agents call tools, the server enforces the workflow definition and owns session state on disk.

      +

      How workflow content is structured on disk — manifests, activities, techniques, resources — is documented in Workflows. The sections below cover how the server enforces runs.

      Canonical source: docs/architecture.md (edit).

      diff --git a/site/specs/artifact-management.html b/site/specs/artifact-management.html index 451878d3..8055c0cb 100644 --- a/site/specs/artifact-management.html +++ b/site/specs/artifact-management.html @@ -24,7 +24,6 @@
    • Getting started
    • IDE setup
    • Concepts
      • -
    • Workflow architecture
    • Running workflows
    @@ -34,6 +33,7 @@ Architecture @@ -34,6 +33,7 @@ Architecture @@ -34,6 +33,7 @@ Architecture @@ -34,6 +33,7 @@ Architecture @@ -34,6 +33,7 @@ Architecture @@ -34,6 +33,7 @@ Architecture
    • Overview
      • +
    • Workflows
    • Dispatch
    • Checkpoints
    • State
      • diff --git a/site/guide/workflow-architecture.html b/site/specs/workflows.html similarity index 95% rename from site/guide/workflow-architecture.html rename to site/specs/workflows.html index cd7f8813..d52d83b8 100644 --- a/site/guide/workflow-architecture.html +++ b/site/specs/workflows.html @@ -18,28 +18,28 @@
      • Home
      • -
        +
        Guide
      • -
        +
        Architecture
        • @@ -83,8 +83,8 @@ @@ -92,7 +92,7 @@

        Workflow architecture

        Workflows are declarative files, not code. This page explains what each file type means, how the pieces connect, and what the server delivers to the agent as work progresses.

        -

        For runtime behaviour (checkpoints, dispatch, fidelity), see server architecture. For file shapes, see the schema reference.

        +

        For server enforcement (checkpoints, dispatch, fidelity), see architecture overview. For file shapes, see the schema reference.

        From 66e85c430cfd71cf1336cdf2fef000303145b8af Mon Sep 17 00:00:00 2001 From: Mike Clay Date: Sat, 11 Jul 2026 10:16:16 +0100 Subject: [PATCH 07/12] Expand Workflows page prose and split concept from example diagrams. Separate generic structure diagrams from work-package examples, add binding and resource figures, and write each section in longer plain language. --- site/specs/workflows.html | 401 +++++++++++++++++++++++++------------- 1 file changed, 267 insertions(+), 134 deletions(-) diff --git a/site/specs/workflows.html b/site/specs/workflows.html index d52d83b8..6ca8393b 100644 --- a/site/specs/workflows.html +++ b/site/specs/workflows.html @@ -108,7 +108,8 @@

        Workflow architecture

        Overview

        -

        Think in two layers. On disk, a workflow is a folder of YAML and markdown. At runtime, the agent asks the server for one piece at a time so its context stays focused on the current step.

        +

        A workflow is a folder of YAML and markdown files. Nothing in that folder is executable code — the files describe a process, and the agent follows the description step by step.

        +

        At runtime the agent does not open those files itself. It calls MCP tools, and the server returns one piece at a time: the workflow overview, then the current activity, then each technique as the worker reaches it. That keeps the agent's context small and focused on the work in front of it.

        @@ -145,125 +146,162 @@

        Overview

        Everything under workflows/<workflow-id>/ in the workflows branch -
        The workflow directory layout. The manifest names the workflow and lists activities; each activity file is an ordered step list; technique steps resolve markdown capability files; techniques may link to resources that load only when needed.
        +
        The four file types in a workflow directory and how they reference each other.

        Workflows

        -

        A workflow is the top-level process — for example work-package for planning and implementing a unit of work. Its manifest (workflow.yaml) declares:

        -
          -
        • Identity — id, name, version
          • -
        • Variables — named slots in session state (with optional defaults seeded at session start)
          • -
        • Activities — the phases the orchestrator can move between
          • -
        • Initial activity — where a new session begins (returned by get_workflow as initialActivity)
          • -
        • Rules and orchestrator techniques — behaviour bundled into the first get_workflow response
          • -
        -

        Workflows do not contain executable code. They describe structure; the agent interprets steps and the server enforces transitions, checkpoints, and session state.

        +

        A workflow is the whole process from start to finish. The work-package workflow, for instance, takes you from opening an issue through planning, implementation, validation, and merge.

        +

        The workflow is defined by a single manifest file, workflow.yaml. That file names the workflow, declares the variables the run will use, lists every activity (phase) the orchestrator can enter, and points at the rules and techniques that apply across the whole run.

        +

        When a session starts, the server reads this manifest. The first get_workflow call returns the orchestrator techniques, the variable definitions, and initialActivity — the id of the activity where work begins. The orchestrator uses that id for its first next_activity call.

        +

        Workflows describe structure only. The agent reads steps and follows them; the server enforces which activity is current, whether a checkpoint is blocking progress, and what values sit in the variable bag.

        - - Inside a workflow manifest - A workflow.yaml manifest connects to variables, a list of activities, rules, and orchestrator techniques. Activities form a sequence the orchestrator moves through; one is marked as the initial activity. + + Workflow manifest contents + workflow.yaml connects to variables, activities, rules, and orchestrator techniques. - - workflow.yaml - id · name · version - - variables[] - session state slots - - activities[] - phase definitions - - rules - workflow + activity - - techniques[] - orchestrator bundle + + workflow.yaml + id · name · version · initialActivity + + variables[] + named session slots + + activities[] + phase file refs + + rules + workflow + activity + + techniques[] + orchestrator bundle - - - - - - - - + + + + + +
        What the workflow manifest holds. Variables and rules span the entire run; the activity list is the set of phases the orchestrator can move between.
        +
        + +
        + + Example: work-package activity path + A sequence of work-package activities from start through complete. + + + + + - - start-wp - initial - - plan-prepare - - implement - - validate - - complete + + start-wp + initial + + plan-prepare + + implement + + validate + + complete + + + + + + - Example path from work-package — transitions pick the next box + Transitions choose which box comes next — not always this straight line -
        What lives in the workflow manifest. Variables and rules apply across the whole run; the activity list is the phase graph the orchestrator walks; initialActivity names the first phase (here, start-wp).
        +
        Example: the work-package workflow moves through these activities. start-wp is the initialActivity; later phases depend on variables set along the way.

        Activities

        -

        An activity is one phase inside a workflow — for example Plan & Prepare or Validate & Commit. Each activity file defines:

        -
          -
        • An ordered steps[] list the worker executes top to bottom (with loops branching locally)
          • -
        • transitions — which activity comes next, often gated by workflow variables
          • -
        • Optional activity-level techniques[] refs the server may bundle into get_activity
          • -
        -

        Only one activity is current in a session at a time. The orchestrator advances with next_activity; the worker loads the new activity with get_activity.

        +

        An activity is one phase of a workflow — a stretch of work with a clear goal. Plan & Prepare, Implement, and Validate are activities inside work-package.

        +

        Each activity lives in its own YAML file under activities/. That file has two main parts: a steps[] list the worker runs from top to bottom, and transitions that say which activity to enter next once the phase is done.

        +

        Only one activity is current at a time. The orchestrator moves between activities with next_activity. The worker loads the new phase with get_activity, which returns the step list and may bundle some techniques up front.

        - - Inside an activity file - An activity YAML file contains an ordered steps list executed top to bottom, then transitions that choose the next activity based on conditions. + + Activity file structure + An activity file contains ordered steps and transitions to other activities. - - activities/plan-prepare.yaml + + activity file id · name · steps[] · transitions - - action — env-prerequisites - - technique — create-plan - - technique — collect-assumptions - - loop — assumption rounds - - transition - when ready → assumptions-review - - transition - else → strategic-review + + step 1 + + step 2 + + step 3 + + loop (optional) + + transition A + when condition → activity X + + transition B + else → activity Y - - - + + - - worker runs steps top → bottom; orchestrator reads transitions after the activity completes + Worker runs steps; orchestrator picks a transition when the phase ends + +
        How an activity file is organised. Steps are the work inside the phase; transitions are the exit routes to other activities.
        +
        + +
        + + Example: plan-prepare activity + Concrete steps from the work-package plan-prepare activity. + + + + + + + + plan-prepare.yaml + + action — env-prerequisites + + technique — create-plan + + technique — collect-assumptions + + loop — assumption rounds + + → assumptions-review + + → strategic-review + + + + + First an action checks the environment, then techniques build the plan and gather assumptions -
        An activity file in practice. The worker executes steps[] in order; when the activity finishes, the orchestrator evaluates transitions against workflow variables to choose the next activity.
        +
        Example: the plan-prepare activity checks prerequisites, runs planning techniques, loops over open assumptions, then transitions onward based on review mode.

        Step kinds

        -

        Every step has a kind. Four kinds appear in activity files today:

        +

        Every entry in steps[] has a kind that tells the agent what sort of work it is. Four kinds are in use today. They always appear in the order written in the file, unless a loop repeats a block or a transition sends the run to another activity.

        @@ -289,9 +327,11 @@

        Step kinds

        Steps run in file order unless a loop or transition sends execution elsewhere -
        The four step kinds. Technique steps delegate to markdown capability definitions; action steps are short agent-interpreted instructions; checkpoint steps gate progress on a user decision; loop steps repeat a nested block.
        +
        The four step kinds and what each one asks the agent to do.
        +

        A technique step is the most common. It points at a markdown capability file and the agent fetches it when the step is reached. An action step is lighter — a short instruction the agent carries out directly, such as checking that a path exists. A checkpoint step stops the run until you make a decision. A loop step repeats a nested list until a condition is met.

        +
        @@ -305,75 +345,168 @@

        Step kinds

        Techniques

        -

        A technique is a markdown file that describes one capability: what it does, what inputs it needs, what outputs it produces, the ordered protocol to follow, and any rules to obey.

        -

        Techniques are addressed with :: paths. A bare name like plan resolves in the current workflow first, then falls back to the shared meta workflow. Paths can nest: review-assumptions::collect is a sub-technique under review-assumptions.

        -

        When the server delivers a technique, it composes it: inherited inputs/outputs and merged rules from ancestor techniques, plus binding annotations that show where each input value comes from and where each output goes. The normative file anatomy is in the technique protocol specification (source).

        +

        A technique is a markdown file that explains how to do one job. It says what the job is, what information it needs going in, what it should produce coming out, the ordered steps to follow, and any rules to respect while doing it.

        +

        Activity steps refer to techniques by path. The server looks up that path, loads the markdown, and sends the composed result to the agent. The agent does not read technique files from the repository on its own.

        +

        Paths use :: separators. A simple name like plan is looked up in the current workflow first. If it is not there, the server tries the shared meta workflow. A nested path like review-assumptions::collect means a sub-technique inside a folder.

        + +
        + + Technique file sections + Standard markdown sections in a technique file. + + + techniques/<name>.md + + Capability + + Inputs + + Outputs + + Protocol + + Rules + + The protocol is the step-by-step instructions the agent follows + +
        The standard sections in a technique file. Full rules are in the technique protocol specification (source).
        +
        - - Technique file and resolution - A technique markdown file has Capability, Inputs, Outputs, Protocol, and Rules sections. A reference resolves in the current workflow first, then falls back to meta. Delivery composes ancestor contracts around the requested technique. + + How a technique reference resolves + Lookup order from step reference to composed delivery. - - techniques/plan.md - - Capability - - Inputs - - Outputs - - Protocol - - Rules - - plan - step technique ref - - current workflow - workflows/<wf>/techniques/ - - meta fallback - workflows/meta/techniques/ - - composed delivery - ancestor Initial/Final - inherited I/O + rules - binding source/dest - step protocol body + + step ref + technique on step + + this workflow + techniques/ folder + + meta + shared fallback + + composed + inherited I/O + merged rules + binding notes - - - - + + + - 1. look here - 2. if missing - Nested refs use subfolders - review-assumptions::collect + 1. try here first + 2. if not found + Delivery wraps ancestor contracts around the technique body -
        Technique anatomy and resolution. The markdown sections are what the agent follows; the server resolves the path workflow-first, then composes ancestor contracts and binding annotations into the wire payload.
        +
        How the server resolves a technique reference and what it sends back. Composition merges parent technique contracts so the agent sees one complete instruction set.
        +
        + +
        + + Example technique paths + Bare and nested technique path examples. + + + plan + + review-assumptions::collect + + bare name + nested sub-technique + +
        Example: plan resolves to techniques/plan.md in the current workflow (or in meta). review-assumptions::collect resolves to a file inside the review-assumptions/ folder.

        Resources

        -

        A resource is reference material — templates, long guides, tables — stored as markdown under resources/. Techniques link to resources instead of inlining them.

        -

        The agent fetches a resource with get_resource only when the technique it is executing needs it. You can request a single section with a #heading-anchor suffix. Resolution rules (bare slug vs meta/bootstrap-protocol cross-workflow refs) are documented on the resolution model page.

        +

        A resource is long-form reference material: a template, a checklist, a table, anything too bulky to paste into a technique. Resources live as markdown files under resources/.

        +

        Techniques link to resources instead of copying them. That keeps technique files short. The agent calls get_resource only when the technique it is running actually needs the linked material.

        +

        You can fetch an entire resource or just one section by adding a #heading-anchor to the id. Cross-workflow references use a prefix, such as meta/bootstrap-protocol. Details are on the resolution model page.

        + +
        + + Technique to resource link + A technique links to a resource that loads on demand. + + + + + + + + technique + links, does not inline + + resource + loaded via get_resource + + + Fetch happens only when the running technique needs it + +
        Techniques point at resources; the agent pulls them in on demand rather than receiving everything up front.
        +
        + +
        + + Example resource fetch + Fetching one section of a resource by anchor. + + + assumption-reconciliation#integration-with-assumptions-log + + Returns only that heading section, not the whole file + +
        Example: a technique that needs one template section fetches just that slice instead of the full resource document.
        +

        Variables and binding

        -

        Workflow variables live in session.json. The server seeds defaults when a session or child workflow starts. Checkpoint options and some step outputs update them as work proceeds.

        -

        When a technique step runs, each declared input is bound from a source the server can see statically: a workflow variable, a value passed on the step, a prior step's output, or a declared default. Each output is mapped to a destination (often a variable or a later step's input). If a binding cannot be resolved, the server surfaces it in the delivered technique so the agent knows what is missing.

        -

        Activity transitions read the same variable bag: the orchestrator picks the next activity by evaluating transition conditions against current state.

        +

        Workflow variables are named values stored in session.json — things like target_path, issue_number, or flags set by checkpoint choices. The server fills in defaults when a session starts; steps and checkpoints update them as the run proceeds.

        +

        When a technique step runs, each input must come from somewhere: a workflow variable, a value written on the step itself, an output from an earlier step, or a default declared in the technique. The server records where each value comes from and where each output should go. If something cannot be resolved, the delivered technique says so plainly.

        +

        The same variables drive transitions. When an activity ends, the orchestrator checks transition conditions against the current variable bag to decide which activity comes next.

        + +
        + + Variable flow through a technique step + Variables and prior outputs feed technique inputs; outputs write back to variables. + + + + + + + + variables + session.json bag + + technique step + inputs → outputs + + transitions + pick next activity + + + + + + + Outputs from a step can update variables that later steps and transitions read + +
        How data moves through a run. Variables feed technique inputs; technique outputs and checkpoint choices write back to the bag; transitions read the bag to choose the next activity.
        +

        Runtime delivery

        -

        The agent does not read workflow files from disk. It calls MCP tools; the server loads definitions and returns only what the current step needs.

        +

        The agent never opens the workflows/ folder directly. Every piece of content arrives through MCP tool calls, and the server decides how much to send based on where the run is.

        +

        The orchestrator and worker play different roles. The orchestrator calls get_workflow once at the start, then next_activity each time the run should move to a new phase. The worker calls get_activity to load the current step list, then get_technique for each technique step (unless the activity response already bundled it).

        +

        Checkpoint steps interrupt this rhythm: the worker yields, the orchestrator presents your choice, and the worker resumes before continuing. Resources load only when a technique the worker is executing links to one.

        @@ -417,10 +550,10 @@

        Runtime delivery

        Checkpoint tools interrupt the loop wherever a checkpoint step appears -
        Typical delivery sequence. After start_session, the orchestrator loads workflow metadata, advances with next_activity, and the worker loads each activity and its techniques. Resources load on demand. Full call ordering is in the protocol guide.
        +
        The usual tool-call order during a run. Full ordering rules and error handling are in the protocol guide.
        -

        get_activity may inline some step techniques up front (based on context_tokens and bundling limits) so the worker can start without an immediate get_technique per step. Gated or oversized techniques still fetch lazily.

        +

        get_activity may include some step techniques inline when the worker passes context_tokens and the content fits the bundling budget. That saves extra get_technique calls at the start of a phase. Techniques that are gated, too large, or not yet needed are still fetched one at a time.

        Normative references

          From e9ac0c443eaac072be96da6e19af7c746c8e1299 Mon Sep 17 00:00:00 2001 From: Mike Clay Date: Sat, 11 Jul 2026 10:36:34 +0100 Subject: [PATCH 08/12] Improve docs site readability, navigation, and diagrams. Use bulleted prose and clearer SVG layouts on Workflows and Resolution pages, split API nested parameters into a scoped table, link Home to index.html to avoid directory listings, and move Design rationale into the Guide section. --- scripts/generate-site-data.ts | 83 ++++++++-- site/api/protocol.html | 15 +- site/api/schemas.html | 13 +- site/api/tools.html | 61 +++---- site/guide/concepts.html | 28 ++-- site/guide/getting-started.html | 13 +- site/guide/ide-setup.html | 13 +- site/{design => guide}/rationale.html | 29 ++-- site/guide/running-workflows.html | 14 +- site/index.html | 27 +-- site/internals/quality-system.html | 15 +- site/internals/request-lifecycle.html | 15 +- site/internals/server-anatomy.html | 15 +- site/internals/session-store.html | 15 +- site/specs/architecture.html | 15 +- site/specs/artifact-management.html | 13 +- site/specs/checkpoints.html | 13 +- site/specs/dispatch.html | 13 +- site/specs/resource-resolution.html | 227 +++++++++++++++++++++++--- site/specs/state-management.html | 13 +- site/specs/workflow-fidelity.html | 13 +- site/specs/workflows.html | 158 ++++++++++++------ site/style.css | 16 ++ 23 files changed, 514 insertions(+), 323 deletions(-) rename site/{design => guide}/rationale.html (95%) diff --git a/scripts/generate-site-data.ts b/scripts/generate-site-data.ts index 381e71e4..9841eadf 100644 --- a/scripts/generate-site-data.ts +++ b/scripts/generate-site-data.ts @@ -23,7 +23,7 @@ const GITHUB_BLOB = 'https://github.com/m2ux/workflow-server/blob/main'; // --------------------------------------------------------------------------- // Site route registry -export type SiteSection = 'home' | 'guide' | 'specs' | 'api' | 'internals' | 'design'; +export type SiteSection = 'home' | 'guide' | 'specs' | 'api' | 'internals'; export interface SiteRoute { relPath: string; @@ -43,6 +43,7 @@ export const SITE_ROUTES: SiteRoute[] = [ { relPath: 'guide/ide-setup.html', section: 'guide', title: 'IDE setup', navLabel: 'IDE setup', sequence: 2 }, { relPath: 'guide/concepts.html', section: 'guide', title: 'Concepts', navLabel: 'Concepts', sequence: 3 }, { relPath: 'guide/running-workflows.html', section: 'guide', title: 'Running workflows', navLabel: 'Running workflows', sequence: 4 }, + { relPath: 'guide/rationale.html', section: 'guide', title: 'Design rationale', navLabel: 'Design rationale', sequence: 5 }, { relPath: 'specs/architecture.html', section: 'specs', title: 'Architecture overview', navLabel: 'Overview', sequence: 0, breadcrumbLabel: 'Architecture' }, { relPath: 'specs/workflows.html', section: 'specs', title: 'Workflow architecture', navLabel: 'Workflows', sequence: 1, parent: 'specs/architecture.html', breadcrumbLabel: 'Workflows' }, { relPath: 'specs/dispatch.html', section: 'specs', title: 'Hierarchical dispatch', navLabel: 'Dispatch', sequence: 2, parent: 'specs/architecture.html', breadcrumbLabel: 'Dispatch' }, @@ -58,7 +59,6 @@ export const SITE_ROUTES: SiteRoute[] = [ { relPath: 'internals/request-lifecycle.html', section: 'internals', title: 'Request lifecycle', navLabel: 'Request lifecycle', sequence: 2 }, { relPath: 'internals/session-store.html', section: 'internals', title: 'Session store', navLabel: 'Session store', sequence: 3 }, { relPath: 'internals/quality-system.html', section: 'internals', title: 'Quality system', navLabel: 'Quality system', sequence: 4 }, - { relPath: 'design/rationale.html', section: 'design', title: 'Design rationale', navLabel: 'Design rationale', sequence: 1 }, ]; const ROUTE_BY_PATH = new Map(SITE_ROUTES.map(r => [r.relPath, r])); @@ -68,7 +68,6 @@ const NAV_SECTIONS: Array<{ id: SiteSection; label: string }> = [ { id: 'specs', label: 'Architecture' }, { id: 'api', label: 'API' }, { id: 'internals', label: 'Internals' }, - { id: 'design', label: 'Design' }, ]; function routePrefix(relPath: string): string { @@ -79,7 +78,7 @@ function routePrefix(relPath: string): string { function hrefFrom(pageRelPath: string, targetRelPath: string): string { if (targetRelPath === 'index.html') { const depth = pageRelPath.split('/').length - 1; - return depth === 0 ? './' : '../'.repeat(depth); + return depth === 0 ? './index.html' : `${'../'.repeat(depth)}index.html`; } const fromDir = dirname(join(SITE_DIR, pageRelPath)); const target = join(SITE_DIR, targetRelPath); @@ -132,10 +131,7 @@ export function renderBreadcrumb(pageRelPath: string): string { const sectionLabel = NAV_SECTIONS.find(s => s.id === route.section)?.label ?? route.section; const hub = routesInSection(route.section).find(r => r.sequence === 0); - if (route.section === 'design') { - crumbs.push({ label: 'Design' }); - crumbs.push({ label: route.navLabel }); - } else if (hub && route.parent === hub.relPath) { + if (hub && route.parent === hub.relPath) { crumbs.push({ label: sectionLabel, href: hrefFrom(pageRelPath, hub.relPath) }); crumbs.push({ label: route.breadcrumbLabel ?? route.navLabel }); } else if (hub && route.relPath === hub.relPath) { @@ -469,19 +465,50 @@ function paramRows(schema: JsonSchemaNode, prefix = '', topLevelOnly = false): s `
        ` + ``, ); - if (prop.type === 'array' && prop.items?.properties) { + if (!topLevelOnly && prop.type === 'array' && prop.items?.properties) { rows.push(...paramRows(prop.items, `${label}[].`, topLevelOnly)); } } return rows; } +function nestedParamRows(schema: JsonSchemaNode): string[] { + const rows: string[] = []; + let groupIndex = 0; + for (const [name, prop] of Object.entries(schema.properties ?? {})) { + if (prop.type !== 'array' || !prop.items?.properties) continue; + const scope = `${name}[]`; + const fields = Object.entries(prop.items.properties); + const itemRequired = new Set(prop.items.required ?? []); + fields.forEach(([field, fieldProp], index) => { + const fullLabel = `${name}[].${field}`; + const notes: string[] = []; + const hint = siteParamDescription(fullLabel, fieldProp.description); + if (hint !== '-') notes.push(richText(hint)); + if (fieldProp.default !== undefined) { + notes.push(`Default: ${escapeHtml(JSON.stringify(fieldProp.default))}`); + } + const groupClass = index === 0 && groupIndex > 0 ? ' param-row--group-start' : ''; + const scopeCell = index === 0 + ? `` + : ''; + rows.push( + ` ${scopeCell}` + + `` + + ``, + ); + }); + groupIndex += 1; + } + return rows; +} + function renderParamTable(schema: JsonSchemaNode, topLevelOnly: boolean): string { const rows = paramRows(schema, '', topLevelOnly); if (rows.length === 0) return ''; return [ '
        ', - '
        KindWhat it isAgent behaviour
        ${escapeHtml(label)}${escapeHtml(typeLabel(prop))}${required.has(name) ? 'yes' : 'no'}${notes.join(' ') || '-'}
        ${escapeHtml(scope)}
        ${escapeHtml(field)}${escapeHtml(typeLabel(fieldProp))}${itemRequired.has(field) ? 'yes' : 'no'}${notes.join(' ') || '-'}
        ', + '
        ', ' ', ' ', ...rows, @@ -491,6 +518,21 @@ function renderParamTable(schema: JsonSchemaNode, topLevelOnly: boolean): string ].join('\n'); } +function renderNestedParamTable(schema: JsonSchemaNode): string { + const rows = nestedParamRows(schema); + if (rows.length === 0) return ''; + return [ + '
        ', + '
        ParameterTypeRequiredDescription
        ', + ' ', + ' ', + ...rows, + ' ', + '
        InFieldTypeRequiredDescription
        ', + '
        ', + ].join('\n'); +} + function renderTool(tool: CapturedTool): string { const lines: string[] = []; const siteGuide = SITE_TOOL_GUIDES[tool.name]; @@ -515,13 +557,20 @@ function renderTool(tool: CapturedTool): string { } if (tool.params) { - const allRows = paramRows(tool.params); const topRows = paramRows(tool.params, '', true); - const hasNested = allRows.length > topRows.length; + const nestedRows = nestedParamRows(tool.params); + const hasNested = nestedRows.length > 0; + const allRows = paramRows(tool.params); if (topRows.length > 0) { - lines.push(renderParamTable(tool.params, true).replace('Parameter', 'Parameter').replace(/^ /gm, ' ')); + lines.push(renderParamTable(tool.params, true)); } - if (hasNested || allRows.length > 6) { + if (hasNested) { + lines.push('
        '); + lines.push(' Nested fields'); + lines.push('

        Each item in these arrays is an object with the fields below.

        '); + lines.push(renderNestedParamTable(tool.params)); + lines.push('
        '); + } else if (allRows.length > 6) { lines.push('
        '); lines.push(' All parameters'); lines.push(renderParamTable(tool.params, false)); @@ -701,6 +750,12 @@ export function renderSitePages(): Array<{ relPath: string; content: string }> { content = injectRegion(content, renderBreadcrumb(relPath), 'BREADCRUMB'); content = injectRegion(content, renderPagination(relPath), 'PAGINATION'); + const homeHref = hrefFrom(relPath, 'index.html'); + content = content.replace( + /Workflow Server<\/a>/, + `Workflow Server`, + ); + const body = renderContentRegion(relPath); if (body !== null) { content = injectRegion(content, body, 'CONTENT'); diff --git a/site/api/protocol.html b/site/api/protocol.html index 8c11924f..6fa0b052 100644 --- a/site/api/protocol.html +++ b/site/api/protocol.html @@ -12,11 +12,11 @@
        - Workflow Server + Workflow Server
        @@ -64,14 +65,6 @@
      -
    • -
      - Design - -
      -
    • GitHub
    @@ -137,7 +130,7 @@

    Warnings: the call succeeded, and left evidence

    -

    Why deviations warn instead of block is a deliberate stance — see detection over prevention.

    +

    Why deviations warn instead of block is a deliberate stance — see detection over prevention.

    The trace

    Every tool call appends an event — tool, timing, outcome, workflow, activity, agent, and any validation warnings — to an in-process, per-session buffer (up to 1,000 sessions; the oldest is evicted beyond that). Each next_activity response additionally carries _meta.trace_token: the events since the previous transition, HMAC-signed into a compact token. The tokens are the durable half of the design — an orchestrator that accumulates them can hand the set to get_trace and reconstruct a tamper-evident account of the run even after the in-memory buffer is gone. Calling get_trace with no tokens returns the live buffer for the session.

    diff --git a/site/api/schemas.html b/site/api/schemas.html index 7a2a93bc..f4b22d43 100644 --- a/site/api/schemas.html +++ b/site/api/schemas.html @@ -12,11 +12,11 @@
    - Workflow Server + Workflow Server diff --git a/site/api/tools.html b/site/api/tools.html index 7cb37dad..1effc498 100644 --- a/site/api/tools.html +++ b/site/api/tools.html @@ -12,11 +12,11 @@
    - Workflow Server + Workflow Server @@ -153,7 +146,7 @@

    start_session

    Child workflows are started with dispatch_child, not start_session.

    - +
    @@ -173,7 +166,7 @@

    get_workflow_status

    If the session is nested under a parent, parent context is included too.

    -
    ParameterTypeRequiredDescription
    workflow_idstringnoWorkflow id to run or dispatch (for example, work-package).
    +
    @@ -192,7 +185,7 @@

    dispatch_child

    When the parent is a temporary meta-bootstrap session, the server first promotes it to a real planning folder on disk, then embeds the child. You can keep using the parent's original session_index.

    -
    ParameterTypeRequiredDescription
    session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
    +
    @@ -218,7 +211,7 @@

    get_workflow

    If some activity files failed to load, activity_load_errors lists them and those activities are omitted from the list.

    -
    ParameterTypeRequiredDescription
    session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
    +
    @@ -237,7 +230,7 @@

    next_activity

    Optional step_manifest and transition_condition help the server validate what you completed. Manifest checks are advisory — mismatches produce warnings, not hard errors.

    -
    ParameterTypeRequiredDescription
    session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
    +
    @@ -249,21 +242,17 @@

    next_activity

    ParameterTypeRequiredDescription
    session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
    - All parameters + Nested fields +

    Each item in these arrays is an object with the fields below.

    - - +
    ParameterTypeRequiredDescription
    + - - - - - - - - - - + + + + +
    InFieldTypeRequiredDescription
    session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
    activity_idstringyesActivity to move to. First call: use initialActivity from get_workflow. Later: use an id from transitions.
    transition_conditionstringnoThe condition name that led to this transition, from the previous activity.
    step_manifestobject[]noSteps completed in the previous activity, for example [{ "step_id": "detect-review-mode", "output": "is_review_mode=false" }]. Omit if no steps ran.
    step_manifest[].step_idstringyesStep id from the activity definition (field name is step_id, not id).
    step_manifest[].outputstringyesShort summary of what the step produced. Use a JSON object when the step has multiple outputs.
    activity_manifestobject[]noHistory of completed activities with outcomes and transition conditions.
    activity_manifest[].activity_idstringyesCompleted activity id.
    activity_manifest[].outcomestringyesShort outcome summary for that activity.
    activity_manifest[].transition_conditionstringnoCondition that led out of that activity, if any.
    step_manifest[]step_idstringyesStep id from the activity definition (field name is step_id, not id).
    outputstringyesShort summary of what the step produced. Use a JSON object when the step has multiple outputs.
    activity_manifest[]activity_idstringyesCompleted activity id.
    outcomestringyesShort outcome summary for that activity.
    transition_conditionstringnoCondition that led out of that activity, if any.
    @@ -280,7 +269,7 @@

    get_activity

    If the session uses persistent context mode (or you pass bundle: "reference"), content you already received may come back as short unchanged markers instead of full text. Pass bundle: "full" to force full delivery.

    - +
    @@ -301,7 +290,7 @@

    yield_checkpoint

    Records the checkpoint as active and returns the session_index for a <checkpoint_yield> block in your output.

    -
    ParameterTypeRequiredDescription
    session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
    +
    @@ -319,7 +308,7 @@

    resume_checkpoint

    Verifies the checkpoint is cleared and returns any variable updates to apply before continuing the activity.

    -
    ParameterTypeRequiredDescription
    session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
    +
    @@ -336,7 +325,7 @@

    present_checkpoint

    Reads from state.activeCheckpoint — no separate checkpoint handle is needed.

    -
    ParameterTypeRequiredDescription
    session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
    +
    @@ -355,7 +344,7 @@

    respond_checkpoint

    Variable effects from the chosen option are applied; type mismatches produce warnings in _meta.validation but do not block the response.

    -
    ParameterTypeRequiredDescription
    session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
    +
    @@ -380,7 +369,7 @@

    get_technique

    Every fetch is recorded for trace and advisory manifest checks on the next next_activity call.

    -
    ParameterTypeRequiredDescription
    session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
    +
    @@ -401,7 +390,7 @@

    get_resource

    Each fetch is logged for observability only; nothing validates that you called it.

    -
    ParameterTypeRequiredDescription
    session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
    +
    @@ -421,7 +410,7 @@

    get_trace

    Pass accumulated trace_tokens from next_activity responses to reconstruct a specific segment. Omit them to read the live in-memory trace for the session.

    -
    ParameterTypeRequiredDescription
    session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
    +
    diff --git a/site/guide/concepts.html b/site/guide/concepts.html index b608a8cb..3050a672 100644 --- a/site/guide/concepts.html +++ b/site/guide/concepts.html @@ -12,11 +12,11 @@
    - Workflow Server + Workflow Server @@ -165,10 +158,21 @@

    Checkpoints — where you stay in control

    Your choice can set workflow variables — picking "skip the audit" or "include migration" changes which activities and steps run afterwards. Some checkpoints define a default option and can auto-advance after a timeout; the server still enforces the timer.

    Techniques and resources

    -

    A technique is a markdown document that tells the agent how to perform one capability. Steps bind techniques by reference; the agent fetches each one just-in-time with get_technique as it reaches the step. Resources load with get_resource only when needed. See Workflows for paths, composition, and binding.

    +

    A technique is a markdown document that tells the agent how to perform one capability. At runtime:

    +
      +
    • activity steps bind techniques by reference
      • +
    • the agent fetches each one just-in-time with get_technique as it reaches the step
      • +
    • resources load with get_resource only when a technique links to one
      • +
    +

    See Workflows for paths, composition, and binding.

    Fidelity: why agents stay on script

    -

    The server enforces the workflow instead of trusting the agent to follow it. Transitions are validated, checkpoints gate advancement, and session state on disk is the single source of truth.

    +

    The server enforces the workflow instead of trusting the agent to follow it:

    +
      +
    • transitions are validated
      • +
    • checkpoints gate advancement
      • +
    • session state on disk is the single source of truth
      • +

    Read workflow fidelity for what each layer protects against, and architecture overview for the six models behind it.

    Next

    diff --git a/site/guide/getting-started.html b/site/guide/getting-started.html index 616ff92e..c0ccc203 100644 --- a/site/guide/getting-started.html +++ b/site/guide/getting-started.html @@ -12,11 +12,11 @@
    - Workflow Server + Workflow Server diff --git a/site/guide/ide-setup.html b/site/guide/ide-setup.html index e8dd6e02..3a1eda70 100644 --- a/site/guide/ide-setup.html +++ b/site/guide/ide-setup.html @@ -12,11 +12,11 @@
    - Workflow Server + Workflow Server diff --git a/site/design/rationale.html b/site/guide/rationale.html similarity index 95% rename from site/design/rationale.html rename to site/guide/rationale.html index bd80ccd5..74c892ae 100644 --- a/site/design/rationale.html +++ b/site/guide/rationale.html @@ -12,19 +12,20 @@
    - Workflow Server + Workflow Server @@ -83,7 +76,7 @@ @@ -147,7 +140,9 @@

    Next

    - +
    ParameterTypeRequiredDescription
    session_indexstringyesSix-character token from start_session. Use the same value for every call in this session.
    @@ -294,7 +281,7 @@

    Where to start

    - + diff --git a/site/internals/quality-system.html b/site/internals/quality-system.html index 13871c85..5d1d3047 100644 --- a/site/internals/quality-system.html +++ b/site/internals/quality-system.html @@ -12,11 +12,11 @@
    - Workflow Server + Workflow Server @@ -177,7 +170,7 @@

    Generated, then guarded

    The same discipline extends to deployment: the GitHub Pages workflow re-runs the site guards before publishing, so the deployed site is exactly the checked, committed one.

    Next

    -

    Why the project invests in mechanical guardrails rather than review vigilance is part of the design rationale; the runtime half of the same philosophy is workflow fidelity.

    +

    Why the project invests in mechanical guardrails rather than review vigilance is part of the design rationale; the runtime half of the same philosophy is workflow fidelity.

    diff --git a/site/internals/request-lifecycle.html b/site/internals/request-lifecycle.html index 2f7f1720..efdc1a48 100644 --- a/site/internals/request-lifecycle.html +++ b/site/internals/request-lifecycle.html @@ -12,11 +12,11 @@
    - Workflow Server + Workflow Server @@ -162,7 +155,7 @@

    4. Fidelity checks

    What do errors and warnings mean?Protocol guide
    How do I author workflow definitions?Schema reference and Schema guide (source)
    How is the system designed?Architecture overview and the six model pages linked from it
    Why is it designed this way?Design rationale
    Why is it designed this way?Design rationale
    How is the server implemented?Server internals
    What keeps agents faithful to a workflow?Workflow fidelity
    How do techniques declare protocol and bindings?Technique protocol (source)
    -

    The split is deliberate: only checks that are cheap and certain block the call; everything judgment-shaped becomes a warning in the response and the trace. Detection over prevention explains why.

    +

    The split is deliberate: only checks that are cheap and certain block the call; everything judgment-shaped becomes a warning in the response and the trace. Detection over prevention explains why.

    5. Advancing the state

    advanceSession applies the mutation as a controlled update: the monotonic seq counter increments, the timestamp refreshes, and the handler's mutator appends history events — activity_exited for the activity being left, activity_entered for the new one, and workflow_completed when the transition is terminal. A child session reaching its terminal state also notifies its parent, flipping the child's entry in the parent's triggeredWorkflows to completed (best-effort — a moved parent is tolerated).

    diff --git a/site/internals/server-anatomy.html b/site/internals/server-anatomy.html index e6746a07..30c3ed01 100644 --- a/site/internals/server-anatomy.html +++ b/site/internals/server-anatomy.html @@ -12,11 +12,11 @@
    - Workflow Server + Workflow Server @@ -202,7 +195,7 @@

    Error discipline

    Where things live on disk

      -
    • Workflow definitions are read from the configured workflow directory — in this repository, the workflows/ worktree of the orphan workflows branch (why an orphan branch).
      • +
    • Workflow definitions are read from the configured workflow directory — in this repository, the workflows/ worktree of the orphan workflows branch (why an orphan branch).
    • Session state is written under <workspace>/.engineering/artifacts/planning/<slug>/ — the session store page covers the folder's contents.
    • The server key lives at ~/.workflow-server/secret, per user, outside any repository.
    diff --git a/site/internals/session-store.html b/site/internals/session-store.html index 262e2244..e37fafc1 100644 --- a/site/internals/session-store.html +++ b/site/internals/session-store.html @@ -12,11 +12,11 @@
    - Workflow Server + Workflow Server @@ -167,7 +160,7 @@

    Nested and transient sessions

    Meta-orchestration sessions that exist only to choose a workflow start transient — created under the system temporary directory with a synthetic slug. The first dispatch_child that commits to real work promotes the session into the workspace planning root, taking its slug from the request (or a dated fallback), and the temporary folder is discarded. Nothing about a browse-only conversation ever lands in your repository.

    Integrity and migration

    -

    The seal answers one question: is this file exactly what the server last wrote? Writes are atomic (temp file, then rename), the HMAC is computed over canonicalized JSON, and reads verify it with a timing-safe comparison before parsing. What it defends against is corruption, manual edits, restored backups, and racing writers — incoherence, not adversaries; the threat model is spelled out in the rationale.

    +

    The seal answers one question: is this file exactly what the server last wrote? Writes are atomic (temp file, then rename), the HMAC is computed over canonicalized JSON, and reads verify it with a timing-safe comparison before parsing. What it defends against is corruption, manual edits, restored backups, and racing writers — incoherence, not adversaries; the threat model is spelled out in the rationale.

    Older planning folders that predate the current layout are upgraded in place by migration.ts the first time they are touched; an upgrade that cannot complete raises MigrationError rather than leaving a half-converted folder.

    Next

    diff --git a/site/specs/architecture.html b/site/specs/architecture.html index 1615dce6..732f6ec0 100644 --- a/site/specs/architecture.html +++ b/site/specs/architecture.html @@ -12,11 +12,11 @@
    - Workflow Server + Workflow Server @@ -181,7 +174,7 @@

    The implementation view

    The models above state the guarantees; two further sections of this site show the machinery and the reasoning behind them:

    diff --git a/site/specs/artifact-management.html b/site/specs/artifact-management.html index 8055c0cb..7a5d0c8e 100644 --- a/site/specs/artifact-management.html +++ b/site/specs/artifact-management.html @@ -12,11 +12,11 @@
    - Workflow Server + Workflow Server diff --git a/site/specs/checkpoints.html b/site/specs/checkpoints.html index 61b26b1b..77d3b310 100644 --- a/site/specs/checkpoints.html +++ b/site/specs/checkpoints.html @@ -12,11 +12,11 @@
    - Workflow Server + Workflow Server diff --git a/site/specs/dispatch.html b/site/specs/dispatch.html index 48d1aa15..4c93d804 100644 --- a/site/specs/dispatch.html +++ b/site/specs/dispatch.html @@ -12,11 +12,11 @@
    - Workflow Server + Workflow Server diff --git a/site/specs/resource-resolution.html b/site/specs/resource-resolution.html index a4cee261..231bfd51 100644 --- a/site/specs/resource-resolution.html +++ b/site/specs/resource-resolution.html @@ -12,11 +12,11 @@
    - Workflow Server + Workflow Server @@ -131,27 +124,223 @@

    Technique and resource resolution

    - - 1. look here first - 2. fallback - grouped into - links rewritten into fetchable refs + + 1. look here first + 2. fallback + grouped into + links rewritten into fetchable refs
    Reference resolution. A reference tries the current workflow's techniques first, then the shared meta layer (a same-named local technique shadows the meta one). The resolved body arrives with its rules auto-included, grouped into a techniques / rules / unresolved bundle; resource links inside it are rewritten into get_resource refs and fetched lazily.

    One kind of technique

    -

    A technique is a markdown file whose slug is its canonical id — standalone (techniques/{slug}.md) or grouped (techniques/{group}/TECHNIQUE.md with nested {sub}.md siblings; a nested technique is itself a technique). Its published shape: identity (id, version, capability), optional inputs and outputs (outputs may carry an artifact filename), an ordered protocol of imperative steps, and named rules — behavioural invariants that ride along with the technique.

    +

    A technique is a markdown file whose slug is its canonical id. There is one kind of technique — standalone files and grouped folders use the same published shape on the wire.

    +
      +
    • Identity — id, version, capability
      • +
    • Inputs / outputs — optional typed slots; outputs may name an artifact filename
      • +
    • Protocol — ordered imperative steps the agent follows
      • +
    • Rules — named behavioural invariants bundled with the technique
      • +
    + +
    + + Technique file layouts + A standalone technique is a single markdown file. A grouped technique is a folder with TECHNIQUE.md and nested sub-technique files. + + + standalone + + techniques/plan.md + slug = filename + + grouped + + review-assumptions/TECHNIQUE.md + + review-assumptions/collect.md + nested ref: review-assumptions::collect + + +
    Two on-disk layouts, one delivery model. A nested {sub}.md is a full technique in its own right — not a fragment of the parent file.
    +

    References

    -

    Activities and workflows compose behaviour by listing ::-delimited references: [workflow::]technique[::nested…]. A same-workflow reference omits the workflow segment; a trailing segment that matches no nested technique is matched against the technique's rule names instead (a group prefix expands to every {group}-* rule). Anything that matches nothing surfaces in the unresolved bucket — never silently dropped.

    +

    Activities and workflows compose behaviour by listing ::-delimited references. The path has up to three parts:

    +
      +
    • Workflow (optional) — omit for the current workflow; prefix to reach another workflow
      • +
    • Technique — standalone slug or group folder name
      • +
    • Nested segment (optional) — sub-technique inside a group, or a rule name if no sub-technique matches
      • +
    +

    A group prefix like agent-conduct can expand to every agent-conduct-* rule. Anything that matches nothing lands in the unresolved bucket — never silently dropped.

    + +
    + + Reference path anatomy + Optional workflow prefix, technique name, optional nested or rule segment, separated by double colons. + + + [workflow::] + :: + + technique + :: + + [nested…] + cross-workflow + required + sub-technique or rule + + +
    The general reference form. Slashes in a path are normalised to :: at resolution time.
    +
    + +
    + + Example technique references + Three example references: bare name, nested sub-technique, and cross-workflow prefixed path. + + + plan + + review-assumptions::collect + + meta::agent-conduct::file-sensitivity + same workflow + nested sub-technique + explicit workflow prefix + Inline invocations in step text resolve to the same bodies + + +
    Example: bare names resolve workflow-first with a meta fallback; nested segments address sub-techniques; a leading workflow segment reaches shared layers explicitly.
    +

    Delivery at workflow and activity granularity

    -

    Agents never chain resolution calls at runtime. get_workflow returns the orchestrator bundle — the workflow's declared references plus the core orchestrator set the server auto-includes (engine traversal, checkpoint flow, dispatch, discipline). get_activity returns the worker bundle — the activity's references, the workflow's inherited techniques.activity, plus the core worker set (yield/resume, finalize, conduct rules). When a technique is delivered, ancestor containers' Initial/Final protocol blocks wrap the technique's own protocol recursively, and the combined sequence is renumbered.

    +

    Agents never chain resolution calls at runtime. The server pre-resolves reference lists into bundles when you call:

    +
      +
    • get_workflow — orchestrator bundle: workflow-declared refs plus core orchestrator techniques (engine traversal, checkpoints, dispatch, discipline)
      • +
    • get_activity — worker bundle: activity refs, inherited techniques.activity from the workflow, plus core worker techniques (yield/resume, finalize, conduct rules)
      • +
    +

    Each bundle groups resolved content into three buckets. When a single technique is delivered, ancestor Initial / Final protocol blocks wrap the technique body recursively and the server renumbers the combined sequence.

    + +
    + + Delivery bundle buckets + Resolved references are grouped into techniques, rules, and unresolved buckets. + + + techniques + path → composed body + + rules + auto-included invariants + + unresolved + explicit misses + + Empty buckets are omitted from the wire response + +
    What a resolved bundle contains. Technique bodies arrive composed; remaining rules ride along; unresolved refs are surfaced plainly.
    +
    + +
    + + Where each bundle comes from + get_workflow and get_activity each union declared references with a core auto-included set, then resolve into the same three buckets. + + + + + + + + get_workflow + + workflow techniques.workflow + + core orchestrator set + + get_activity + + activity techniques[] + + workflow techniques.activity + + core worker set + + resolved bundle + techniques · rules · unresolved + + + + + + + + + + + +
    Two entry points, one bundle shape. Orchestrator and worker each receive the union of what their YAML declares and what the server always includes for that role. Duplicates are deduplicated before resolution.
    +

    Resources: lazy by design

    -

    Large reference material — CLI guides, templates, API notes — never rides along in bundles. A technique links a resource with an ordinary markdown hyperlink; at delivery the server rewrites those links into get_resource-callable refs ({id}[#section], or {workflow}/{id}[#section] across workflows). The agent fetches one only when it actually needs it, and a #section anchor narrows the fetch to a single heading — a template, not the whole file.

    +

    Large reference material — CLI guides, templates, API notes — never rides along in technique bundles. At delivery time the server rewrites markdown hyperlinks inside a technique into fetchable get_resource refs. The agent calls get_resource only when the running technique actually needs the linked material.

    +

    Resource ids support:

    +
      +
    • Bare slug — resolved in the session's current workflow
      • +
    • Workflow prefix — meta/activity-worker-prompt pulls from another workflow's resources/ folder
      • +
    • Section anchor — #heading-slug returns one heading block, not the whole file
      • +
    + +
    + + From markdown link to fetchable ref + A technique contains a markdown hyperlink; delivery rewrites it; the agent calls get_resource when needed. + + + + + + + + technique body + markdown hyperlink + + delivery rewrite + callable resource ref + + agent + needs content + + get_resource + + workflows/<wf>/resources/<slug>.md + + + + + + + + + on demand + +
    Resources stay out of bundles. The technique carries a ref; the agent fetches the markdown file when execution reaches the link.
    +
    + +
    + + Example resource fetch + A cross-workflow resource id with an optional section anchor. + + + meta/activity-worker-prompt#worker-brief + + Loads from meta/resources/ and returns only the worker-brief section + +
    Example: prefixed ids reach shared libraries; #section narrows a large resource to the template the technique actually needs.
    +

    How techniques declare inputs/outputs and how binding works is the technique protocol specification; what the resolved bundles look like on the wire is in the tool reference.

    diff --git a/site/specs/state-management.html b/site/specs/state-management.html index 88ba8dd7..866f1e41 100644 --- a/site/specs/state-management.html +++ b/site/specs/state-management.html @@ -12,11 +12,11 @@
    - Workflow Server + Workflow Server diff --git a/site/specs/workflow-fidelity.html b/site/specs/workflow-fidelity.html index d39728ef..50ee8bc8 100644 --- a/site/specs/workflow-fidelity.html +++ b/site/specs/workflow-fidelity.html @@ -12,11 +12,11 @@
    - Workflow Server + Workflow Server diff --git a/site/specs/workflows.html b/site/specs/workflows.html index 6ca8393b..5b191102 100644 --- a/site/specs/workflows.html +++ b/site/specs/workflows.html @@ -12,11 +12,11 @@
    - Workflow Server + Workflow Server @@ -108,8 +101,12 @@

    Workflow architecture

    Overview

    -

    A workflow is a folder of YAML and markdown files. Nothing in that folder is executable code — the files describe a process, and the agent follows the description step by step.

    -

    At runtime the agent does not open those files itself. It calls MCP tools, and the server returns one piece at a time: the workflow overview, then the current activity, then each technique as the worker reaches it. That keeps the agent's context small and focused on the work in front of it.

    +

    Think in two layers:

    +
      +
    • On disk — a workflow is a folder of YAML and markdown. Nothing in it is executable code; the files describe a process the agent follows step by step.
      • +
    • At runtime — the agent does not open those files. It calls MCP tools, and the server returns one piece at a time: the workflow overview, then the current activity, then each technique as the worker reaches it.
      • +
    +

    Delivering content in small pieces keeps the agent's context focused on the work in front of it.

    @@ -151,9 +148,26 @@

    Overview

    Workflows

    A workflow is the whole process from start to finish. The work-package workflow, for instance, takes you from opening an issue through planning, implementation, validation, and merge.

    -

    The workflow is defined by a single manifest file, workflow.yaml. That file names the workflow, declares the variables the run will use, lists every activity (phase) the orchestrator can enter, and points at the rules and techniques that apply across the whole run.

    -

    When a session starts, the server reads this manifest. The first get_workflow call returns the orchestrator techniques, the variable definitions, and initialActivity — the id of the activity where work begins. The orchestrator uses that id for its first next_activity call.

    -

    Workflows describe structure only. The agent reads steps and follows them; the server enforces which activity is current, whether a checkpoint is blocking progress, and what values sit in the variable bag.

    +

    The workflow is defined by a single manifest file, workflow.yaml. That file holds:

    +
      +
    • Identity — id, name, version
      • +
    • Variables — named slots in session state, with optional defaults seeded at session start
      • +
    • Activities — the phases the orchestrator can move between
      • +
    • Initial activity — where a new session begins
      • +
    • Rules and orchestrator techniques — behaviour that applies across the whole run
      • +
    +

    When a session starts, the server reads this manifest. The first get_workflow call returns:

    +
      +
    • orchestrator techniques and rules
      • +
    • variable definitions
      • +
    • initialActivity — the id of the activity where work begins
      • +
    +

    The orchestrator uses initialActivity for its first next_activity call. After that, workflows describe structure only: the agent follows steps, and the server enforces:

    +
      +
    • which activity is current
      • +
    • whether a checkpoint is blocking progress
      • +
    • what values sit in the variable bag
      • +
    @@ -226,8 +240,16 @@

    Workflows

    Activities

    An activity is one phase of a workflow — a stretch of work with a clear goal. Plan & Prepare, Implement, and Validate are activities inside work-package.

    -

    Each activity lives in its own YAML file under activities/. That file has two main parts: a steps[] list the worker runs from top to bottom, and transitions that say which activity to enter next once the phase is done.

    -

    Only one activity is current at a time. The orchestrator moves between activities with next_activity. The worker loads the new phase with get_activity, which returns the step list and may bundle some techniques up front.

    +

    Each activity lives in its own YAML file under activities/. That file has two main parts:

    +
      +
    • steps[] — the ordered list the worker runs from top to bottom
      • +
    • transitions — rules for which activity to enter next once the phase is done
      • +
    +

    Only one activity is current at a time. Two roles split the work:

    +
      +
    • Orchestrator — calls next_activity to move between phases
      • +
    • Worker — calls get_activity to load the step list (and may receive bundled techniques up front)
      • +
    @@ -301,7 +323,7 @@

    Activities

    Step kinds

    -

    Every entry in steps[] has a kind that tells the agent what sort of work it is. Four kinds are in use today. They always appear in the order written in the file, unless a loop repeats a block or a transition sends the run to another activity.

    +

    Every entry in steps[] has a kind that tells the agent what sort of work it is. Four kinds are in use today. They run in file order unless a loop repeats a block or a transition sends the run to another activity.

    @@ -330,8 +352,6 @@

    Step kinds

    The four step kinds and what each one asks the agent to do.
    -

    A technique step is the most common. It points at a markdown capability file and the agent fetches it when the step is reached. An action step is lighter — a short instruction the agent carries out directly, such as checking that a path exists. A checkpoint step stops the run until you make a decision. A loop step repeats a nested list until a condition is met.

    -
    @@ -345,9 +365,21 @@

    Step kinds

    Techniques

    -

    A technique is a markdown file that explains how to do one job. It says what the job is, what information it needs going in, what it should produce coming out, the ordered steps to follow, and any rules to respect while doing it.

    +

    A technique is a markdown file that explains how to do one job. A typical file covers:

    +
      +
    • Capability — what the job is
      • +
    • Inputs — what information it needs going in
      • +
    • Outputs — what it should produce coming out
      • +
    • Protocol — the ordered steps to follow
      • +
    • Rules — constraints to respect while doing it
      • +

    Activity steps refer to techniques by path. The server looks up that path, loads the markdown, and sends the composed result to the agent. The agent does not read technique files from the repository on its own.

    -

    Paths use :: separators. A simple name like plan is looked up in the current workflow first. If it is not there, the server tries the shared meta workflow. A nested path like review-assumptions::collect means a sub-technique inside a folder.

    +

    Paths use :: separators. Resolution works like this:

    +
      +
    • A simple name like plan is looked up in the current workflow first
      • +
    • If it is not there, the server tries the shared meta workflow
      • +
    • A nested path like review-assumptions::collect points at a sub-technique inside a folder
      • +
    @@ -373,7 +405,7 @@

    Techniques

    - + How a technique reference resolves Lookup order from step reference to composed delivery. @@ -382,30 +414,32 @@

    Techniques

    - - step ref - technique on step - - this workflow - techniques/ folder - - meta - shared fallback - - composed - inherited I/O - merged rules - binding notes + + step ref + technique on step + + current workflow + workflows/<wf>/techniques/ + + meta fallback + workflows/meta/techniques/ + + composed + inherited I/O + merged rules + binding notes + protocol body - - - + + + + - - 1. try here first - 2. if not found - Delivery wraps ancestor contracts around the technique body + + 1. try here first + 2. if not found + Delivery wraps ancestor contracts around the technique body
    How the server resolves a technique reference and what it sends back. Composition merges parent technique contracts so the agent sees one complete instruction set.
    @@ -430,7 +464,13 @@

    Techniques

    Resources

    A resource is long-form reference material: a template, a checklist, a table, anything too bulky to paste into a technique. Resources live as markdown files under resources/.

    Techniques link to resources instead of copying them. That keeps technique files short. The agent calls get_resource only when the technique it is running actually needs the linked material.

    -

    You can fetch an entire resource or just one section by adding a #heading-anchor to the id. Cross-workflow references use a prefix, such as meta/bootstrap-protocol. Details are on the resolution model page.

    +

    When fetching, you can:

    +
      +
    • load an entire resource by id
      • +
    • load one section by adding a #heading-anchor to the id
      • +
    • reference another workflow with a prefix, such as meta/bootstrap-protocol
      • +
    +

    Full resolution rules are on the resolution model page.

    @@ -470,7 +510,14 @@

    Resources

    Variables and binding

    Workflow variables are named values stored in session.json — things like target_path, issue_number, or flags set by checkpoint choices. The server fills in defaults when a session starts; steps and checkpoints update them as the run proceeds.

    -

    When a technique step runs, each input must come from somewhere: a workflow variable, a value written on the step itself, an output from an earlier step, or a default declared in the technique. The server records where each value comes from and where each output should go. If something cannot be resolved, the delivered technique says so plainly.

    +

    When a technique step runs, each input must come from somewhere:

    +
      +
    • a workflow variable
      • +
    • a value written on the step itself
      • +
    • an output from an earlier step
      • +
    • a default declared in the technique
      • +
    +

    The server records where each value comes from and where each output should go. If something cannot be resolved, the delivered technique says so plainly.

    The same variables drive transitions. When an activity ends, the orchestrator checks transition conditions against the current variable bag to decide which activity comes next.

    @@ -505,8 +552,16 @@

    Variables and binding

    Runtime delivery

    The agent never opens the workflows/ folder directly. Every piece of content arrives through MCP tool calls, and the server decides how much to send based on where the run is.

    -

    The orchestrator and worker play different roles. The orchestrator calls get_workflow once at the start, then next_activity each time the run should move to a new phase. The worker calls get_activity to load the current step list, then get_technique for each technique step (unless the activity response already bundled it).

    -

    Checkpoint steps interrupt this rhythm: the worker yields, the orchestrator presents your choice, and the worker resumes before continuing. Resources load only when a technique the worker is executing links to one.

    +

    The orchestrator and worker play different roles:

    +
      +
    • Orchestrator — calls get_workflow once at the start, then next_activity each time the run should move to a new phase
      • +
    • Worker — calls get_activity to load the current step list, then get_technique for each technique step (unless the activity response already bundled it)
      • +
    +

    Two patterns interrupt that rhythm:

    +
      +
    • Checkpoints — the worker yields, the orchestrator presents your choice, and the worker resumes before continuing
      • +
    • Resources — load only when a technique the worker is executing links to one
      • +
    @@ -553,7 +608,12 @@

    Runtime delivery

    The usual tool-call order during a run. Full ordering rules and error handling are in the protocol guide.
    -

    get_activity may include some step techniques inline when the worker passes context_tokens and the content fits the bundling budget. That saves extra get_technique calls at the start of a phase. Techniques that are gated, too large, or not yet needed are still fetched one at a time.

    +

    get_activity may include some step techniques inline when the worker passes context_tokens and the content fits the bundling budget. That saves extra get_technique calls at the start of a phase. Techniques that are still fetched one at a time include those that are:

    +
      +
    • gated behind a condition
      • +
    • too large for the bundle
      • +
    • not yet needed in the step order
      • +

    Normative references

      diff --git a/site/style.css b/site/style.css index b2ec2784..ad98b2b6 100644 --- a/site/style.css +++ b/site/style.css @@ -485,6 +485,22 @@ tbody tr:last-child td { border-bottom: none; } .tool-summary { color: var(--text-muted); } +.param-table .param-scope { + color: var(--text-muted); + font-size: 0.92rem; + white-space: nowrap; + vertical-align: top; + border-right: 1px solid var(--border); +} + +.param-table--nested tbody tr.param-row--nested td { + border-top: 1px solid var(--border); +} + +.param-table--nested tbody tr.param-row--group-start td { + border-top-width: 2px; +} + .no-params { color: var(--text-muted); font-style: italic; } /* Footer */ From 7540bbc220ed561a16b7a7fa2373c5413c2a85d3 Mon Sep 17 00:00:00 2001 From: Mike Clay Date: Sat, 11 Jul 2026 10:42:27 +0100 Subject: [PATCH 09/12] Consolidate docs site content to reduce duplication. Remove redundant home sections, shorten workflows and rationale pages with canonical links, and dedupe verify steps between getting-started and ide-setup. --- site/guide/concepts.html | 2 +- site/guide/ide-setup.html | 7 +- site/guide/rationale.html | 9 +- site/index.html | 122 ++----------------------- site/specs/workflows.html | 182 ++------------------------------------ 5 files changed, 21 insertions(+), 301 deletions(-) diff --git a/site/guide/concepts.html b/site/guide/concepts.html index 3050a672..eb2d2d36 100644 --- a/site/guide/concepts.html +++ b/site/guide/concepts.html @@ -164,7 +164,7 @@

      Techniques and resources

    • the agent fetches each one just-in-time with get_technique as it reaches the step
    • resources load with get_resource only when a technique links to one
    -

    See Workflows for paths, composition, and binding.

    +

    On-disk layout: Workflows. Path resolution, composition, and lazy loading: Resolution.

    Fidelity: why agents stay on script

    The server enforces the workflow instead of trusting the agent to follow it:

    diff --git a/site/guide/ide-setup.html b/site/guide/ide-setup.html index 3a1eda70..74031382 100644 --- a/site/guide/ide-setup.html +++ b/site/guide/ide-setup.html @@ -104,11 +104,8 @@

    Schema awareness (optional)

    The server exposes its JSON Schemas via the MCP resource workflow-server://schemas. Agents that author or validate workflow definitions can fetch it on startup — the same schemas are browsable in the schema reference.

    Verifying the connection

    -
      -
    1. Restart your MCP client after adding the rule.
      2. -
    2. Ask the agent to list available workflows. It should call list_workflows and return the inventory — no session needed.
      3. -
    3. Ask it to start a work-package workflow. It should call discover first, then proceed through list_workflows, start_session, and get_workflow.
      4. -
    +

    After restarting your MCP client, confirm the basic connection in Getting started → Verify (list workflows).

    +

    Then test the IDE rule — ask the agent to start a work-package workflow. It should call discover first, then proceed through list_workflows, start_session, and get_workflow.

    If the agent skips discover, the rule has not been picked up — re-check your IDE's rule configuration.

    diff --git a/site/guide/rationale.html b/site/guide/rationale.html index 74c892ae..32e6c408 100644 --- a/site/guide/rationale.html +++ b/site/guide/rationale.html @@ -126,13 +126,16 @@

    Workflow data on an orphan branch

    How the project keeps itself honest

    Detection over prevention

    -

    Of the seven fidelity layers, only the cheap-and-certain ones block: seal verification and the checkpoint gate. Everything that requires interpretation — manifest completeness, version drift, fetch coverage — warns instead. The stance is deliberate humility about what a server can know: it cannot verify that work was done well, only that the observable record is consistent. Hard-blocking on heuristics would teach agents to game the heuristic; surfacing warnings in _meta and the trace gives the orchestrator and the human the evidence and leaves judgment where it belongs. The fidelity page's "honest limitations" section is part of the design, not an apology.

    +

    Only cheap-and-certain checks block; interpretive ones warn.

    +

    Of the seven fidelity layers, seal verification and the checkpoint gate hard-block. Manifest completeness, version drift, and fetch coverage surface warnings in _meta and the trace instead. See workflow fidelity for what each layer does and its honest limitations.

    Guards, anti-patterns, baselines

    -

    Recurring authoring mistakes get codified three ways: a named anti-pattern in the engineering catalogue, a mechanical guard that detects it, and a baseline that ratchets existing violations toward zero (the quality system). The insight is that in a system whose "code" is largely YAML and markdown, convention enforcement cannot live in reviewer vigilance — reviewers tire, agents don't reread style guides, but a failing check is unarguable. The same move recurs at every level of the project: turn a lesson into a machine that remembers it.

    +

    Turn recurring authoring mistakes into mechanical checks.

    +

    Named anti-patterns, guards, and baselines ratchet violations toward zero — see the quality system. In a YAML-and-markdown codebase, convention enforcement cannot live in reviewer vigilance alone.

    A hand-authored documentation site

    -

    This site replaced a static-site-generator pipeline with plain HTML, one stylesheet, and inline SVG. For a documentation set this size, the toolchain cost more than it gave: themes fought the content, and nothing guaranteed the rendered site matched the source of truth. The current arrangement inverts that — markdown in the repository stays canonical, pages that mirror the code are generated and drift-tested, and link and diagram integrity are enforced by the same guard suite as everything else. The docs are treated like the workflows: content with executable invariants.

    +

    Plain HTML with generated pages where the code is the source of truth.

    +

    This site replaced a static-site-generator pipeline with hand-authored pages, one stylesheet, and inline SVG. API and schema pages are generated and drift-tested; link and diagram integrity ride the same guard suite as everything else.

    Next

    See these decisions as running code in the internals section, or as guarantees in the architecture models.

    diff --git a/site/index.html b/site/index.html index c896900c..c40fa869 100644 --- a/site/index.html +++ b/site/index.html @@ -131,32 +131,6 @@

    Structured workflows for AI agents

    -
    -

    Start here

    -

    Pick the path that matches what you need. Every link below goes to a page on this site.

    - -

    Recommended guide order: Getting started → IDE setup → Concepts → Running workflows → Design rationale. For workflow file structure, see Architecture → Workflows.

    -
    -

    How it works

    @@ -170,108 +144,22 @@

    For users

    - For agent implementers: the tool loop -

    Under the hood, the agent follows a bootstrap procedure returned by discover. You do not call these tools yourself; the IDE rule routes workflow requests here.

    -
      -
    1. Discover. discover returns available workflows and the bootstrap sequence.
      2. -
    2. Start a session. start_session and get_workflow open a run and load the workflow structure.
      3. -
    3. Navigate. next_activity and get_activity advance through phases. get_resource loads reference material on demand.
      4. -
    4. Execute. The agent works each activity, yielding at checkpoints until the workflow completes.
      5. -
    -

    Full signatures: MCP tool reference. Call ordering and errors: Protocol guide.

    + For agent implementers +

    The agent follows a bootstrap procedure returned by discover — you do not call MCP tools yourself; the IDE rule routes workflow requests here.

    +

    Tool reference (16 tools, generated from source). Protocol guide for call order, checkpoints, errors, and reference delivery. Workflows for orchestrator vs worker roles.

    - -
    - - A workflow session - Six stages connected by arrows: discover, then start_session, then get_workflow, then next_activity, then get_activity, then work the activity. An arrow loops from work-the-activity back to next_activity, repeating until the final activity completes. - - - - - - - - discover - - start_session - - get_workflow - - next_activity - - get_activity - - work the - activity - - - - - - - - - - repeat for each activity until the workflow completes - -
    A workflow session. After discover, start_session, and get_workflow, the agent loops through next_activity → get_activity → doing the work, one activity at a time, until the workflow completes.
    -
    -
    - -
    -

    All documentation

    -

    This site is the browsable, illustrated view. Markdown in the repository is what you edit when you change the docs.

    - - -

    MCP tools at a glance

    -
    -
    KindWhat it isAgent behaviour
    - - - - - - - - - - - -
    ConcernTools
    Bootstrap (no session token)discover, list_workflows, health_check
    Sessionstart_session, get_workflow_status, dispatch_child
    Workflow / activity navigationget_workflow, next_activity, get_activity
    Checkpoint flowyield_checkpoint, resume_checkpoint, present_checkpoint, respond_checkpoint
    Techniques, resourcesget_technique, get_resource
    Traceget_trace
    -

    Where to start

    -

    Match your question to a page. Site links are for reading; GitHub links are for editing source or docs with no HTML mirror.

    +

    Match your question to a page. This site is the browsable view; markdown in the repository is what you edit when you change the docs.

    + diff --git a/site/specs/workflows.html b/site/specs/workflows.html index 5b191102..b97ebe54 100644 --- a/site/specs/workflows.html +++ b/site/specs/workflows.html @@ -106,7 +106,7 @@

    Overview

  • On disk — a workflow is a folder of YAML and markdown. Nothing in it is executable code; the files describe a process the agent follows step by step.
  • At runtime — the agent does not open those files. It calls MCP tools, and the server returns one piece at a time: the workflow overview, then the current activity, then each technique as the worker reaches it.
    • -

    Delivering content in small pieces keeps the agent's context focused on the work in front of it.

    +

    Delivering content in small pieces keeps the agent's context focused on the work in front of it. See progressive disclosure in Design rationale for why.

    @@ -365,21 +365,8 @@

    Step kinds

    Techniques

    -

    A technique is a markdown file that explains how to do one job. A typical file covers:

    -
      -
    • Capability — what the job is
      • -
    • Inputs — what information it needs going in
      • -
    • Outputs — what it should produce coming out
      • -
    • Protocol — the ordered steps to follow
      • -
    • Rules — constraints to respect while doing it
      • -
    -

    Activity steps refer to techniques by path. The server looks up that path, loads the markdown, and sends the composed result to the agent. The agent does not read technique files from the repository on its own.

    -

    Paths use :: separators. Resolution works like this:

    -
      -
    • A simple name like plan is looked up in the current workflow first
      • -
    • If it is not there, the server tries the shared meta workflow
      • -
    • A nested path like review-assumptions::collect points at a sub-technique inside a folder
      • -
    +

    A technique is a markdown file that explains how to do one job — capability, inputs, outputs, protocol, and rules. Activity steps refer to techniques by path; the agent never reads those files from the repository directly.

    +

    Path resolution, composition, and delivery are on Resolution. This page covers on-disk layout only.

    @@ -404,109 +391,9 @@

    Techniques

    The standard sections in a technique file. Full rules are in the technique protocol specification (source).
    -
    - - How a technique reference resolves - Lookup order from step reference to composed delivery. - - - - - - - - step ref - technique on step - - current workflow - workflows/<wf>/techniques/ - - meta fallback - workflows/meta/techniques/ - - composed - inherited I/O - merged rules - binding notes - protocol body - - - - - - - - - 1. try here first - 2. if not found - Delivery wraps ancestor contracts around the technique body - - -
    How the server resolves a technique reference and what it sends back. Composition merges parent technique contracts so the agent sees one complete instruction set.
    -
    - -
    - - Example technique paths - Bare and nested technique path examples. - - - plan - - review-assumptions::collect - - bare name - nested sub-technique - -
    Example: plan resolves to techniques/plan.md in the current workflow (or in meta). review-assumptions::collect resolves to a file inside the review-assumptions/ folder.
    -
    -

    Resources

    -

    A resource is long-form reference material: a template, a checklist, a table, anything too bulky to paste into a technique. Resources live as markdown files under resources/.

    -

    Techniques link to resources instead of copying them. That keeps technique files short. The agent calls get_resource only when the technique it is running actually needs the linked material.

    -

    When fetching, you can:

    -
      -
    • load an entire resource by id
      • -
    • load one section by adding a #heading-anchor to the id
      • -
    • reference another workflow with a prefix, such as meta/bootstrap-protocol
      • -
    -

    Full resolution rules are on the resolution model page.

    - -
    - - Technique to resource link - A technique links to a resource that loads on demand. - - - - - - - - technique - links, does not inline - - resource - loaded via get_resource - - - Fetch happens only when the running technique needs it - -
    Techniques point at resources; the agent pulls them in on demand rather than receiving everything up front.
    -
    - -
    - - Example resource fetch - Fetching one section of a resource by anchor. - - - assumption-reconciliation#integration-with-assumptions-log - - Returns only that heading section, not the whole file - -
    Example: a technique that needs one template section fetches just that slice instead of the full resource document.
    -
    +

    A resource is long-form reference material — templates, checklists, tables — stored as markdown under resources/. Techniques link to resources instead of inlining them; the agent calls get_resource only when a running technique needs the linked material.

    +

    Resolution rules, section anchors, and cross-workflow prefixes are on Resolution.

    Variables and binding

    Workflow variables are named values stored in session.json — things like target_path, issue_number, or flags set by checkpoint choices. The server fills in defaults when a session starts; steps and checkpoints update them as the run proceeds.

    @@ -562,65 +449,10 @@

    Runtime delivery

  • Checkpoints — the worker yields, the orchestrator presents your choice, and the worker resumes before continuing
  • Resources — load only when a technique the worker is executing links to one
    • - -
    - - Typical tool sequence - A left-to-right sequence of MCP tool calls from start_session through get_workflow, next_activity, get_activity, get_technique, and optional get_resource. - - - - - - - - start_session - session_index - - get_workflow - initialActivity - - next_activity - advance state - - get_activity - steps + bundle - - get_technique - per step - - get_resource - when linked - - - - - - - - - - Orchestrator calls next_activity; worker calls get_activity and get_technique - Repeat the next_activity → get_activity → get_technique loop for each activity - Checkpoint tools interrupt the loop wherever a checkpoint step appears - - -
    The usual tool-call order during a run. Full ordering rules and error handling are in the protocol guide.
    -
    - -

    get_activity may include some step techniques inline when the worker passes context_tokens and the content fits the bundling budget. That saves extra get_technique calls at the start of a phase. Techniques that are still fetched one at a time include those that are:

    -
      -
    • gated behind a condition
      • -
    • too large for the bundle
      • -
    • not yet needed in the step order
      • -
    +

    Tool call order, bundling, and errors are in the protocol guide. Technique and resource resolution are on Resolution.

    Normative references

    - +

    JSON shapes: schema reference. Authoritative prose specs: architecture overview → Normative specifications.

    Next

    Concepts covers sessions and checkpoints from a user perspective. Dispatch explains how orchestrators and workers run those workflows.

    From 801b39676e94bd22d5469a28b19c5f3e8798c758 Mon Sep 17 00:00:00 2001 From: Mike Clay Date: Sat, 11 Jul 2026 10:48:21 +0100 Subject: [PATCH 10/12] Explain why techniques use a formal contract shape, not skills. Add a rationale section comparing technique structure to conventional agent skills, and cross-link from Concepts. --- site/guide/concepts.html | 2 +- site/guide/rationale.html | 13 ++++++++++++- 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/site/guide/concepts.html b/site/guide/concepts.html index eb2d2d36..add4e739 100644 --- a/site/guide/concepts.html +++ b/site/guide/concepts.html @@ -164,7 +164,7 @@

    Techniques and resources

  • the agent fetches each one just-in-time with get_technique as it reaches the step
  • resources load with get_resource only when a technique links to one
    • -

    On-disk layout: Workflows. Path resolution, composition, and lazy loading: Resolution.

    +

    On-disk layout: Workflows. Path resolution, composition, and lazy loading: Resolution. Techniques differ from conventional agent skills (description-triggered instruction packages) — see Design rationale → Why techniques, not skills?.

    Fidelity: why agents stay on script

    The server enforces the workflow instead of trusting the agent to follow it:

    diff --git a/site/guide/rationale.html b/site/guide/rationale.html index 32e6c408..4608f976 100644 --- a/site/guide/rationale.html +++ b/site/guide/rationale.html @@ -118,7 +118,18 @@

    Three layers of dispatch

    How behaviour is defined

    Techniques are markdown with a contract

    -

    Process knowledge is written in markdown files with declared inputs, outputs, protocol, and rules — parseable enough for the server to compose, validate, and bind them; readable enough for a human to review in a pull request and an agent to follow verbatim. The alternative poles were both rejected: free-form prose cannot be checked, and a rigid programmatic format cannot hold the judgment-laden guidance that makes techniques worth having. The contract layer (typed identifiers, binding provenance, inheritance) grew precisely at the seams where prose had proven unreliable.

    +

    Structured capabilities the server can compose, bind, and deliver — not ambient skill prompts.

    +

    Process knowledge is written in markdown with declared inputs, outputs, an ordered protocol, and optional rules — parseable enough for the server to compose, validate, and bind them; readable enough for a human to review in a pull request and an agent to follow verbatim. The alternative poles were both rejected: free-form prose cannot be checked, and a rigid programmatic format cannot hold the judgment-laden guidance that makes techniques worth having.

    + +

    Why techniques, not skills?

    +

    Agent platforms popularised skills — markdown packages with a short description and instructions the model loads when a request seems to match. That shape works well for ambient, opt-in guidance. This server orchestrates multi-step workflows where an activity step names a capability, the server binds it to session variables, and fidelity depends on knowing exactly what was delivered.

    +
      +
    • Formal sections — Capability, Inputs, Outputs, Protocol, and Rules are canonical and schema-checked (schema reference), so the server can merge ancestor contracts, wrap protocols with container Initial/Final blocks, and flag definition defects — not merely paste prose into context.
      • +
    • Granular composition — nested :: paths, grouped folders, and per-activity techniques[] lists let one activity assemble exactly the capabilities it needs (Resolution).
      • +
    • Precision delivery — the server delivers workflow metadata, then one activity, then step techniques and resources on demand (progressive disclosure), with bundling budgets and fetch recording — not whole skill files chosen by trigger matching.
      • +
    • Protocol vs reference — the protocol states imperative steps to execute; bulky templates, checklists, and API guides live in resources/ and load via get_resource only when a running technique links to them (Workflows → Resources). Skills conventionally mix procedure and reference in one package; here the split is structural.
      • +
    +

    The contract layer — typed identifiers, binding provenance, inheritance — exists where orchestration needs mechanical guarantees, not model discretion. See Workflows for on-disk layout and technique protocol (source) for the normative file shape.

    Workflow data on an orphan branch

    Workflow definitions live on a workflows branch with no shared history with main, checked out as a worktree. The two bodies change for different reasons on different cadences: server releases are code events; workflow edits are content events, often several per day while a process is being tuned. Separate histories mean content changes never entangle server review, a deployment can pin either side independently, and the same server can mount a different corpus per project. The cost is a two-step setup (git worktree add) and the standing rule that content PRs and server PRs stay separate.

    From 14906eb1731f9cd9c4ca65e32414158b0bf693a5 Mon Sep 17 00:00:00 2001 From: Mike Clay Date: Sat, 11 Jul 2026 11:53:14 +0100 Subject: [PATCH 11/12] Restructure documentation site navigation, content, and diagrams. Reorganize nav (definitions, specifications, design), consolidate getting started, refine the home run diagram and copy, and move internals under design. --- .agents/skills/design-taste-frontend/SKILL.md | 1206 +++++++++++++++++ .agents/skills/imagegen-frontend-web/SKILL.md | 987 ++++++++++++++ .agents/skills/minimalist-ui/SKILL.md | 85 ++ .agents/skills/stitch-design-taste/DESIGN.md | 121 ++ .agents/skills/stitch-design-taste/SKILL.md | 184 +++ .claude/skills/design-taste-frontend | 1 + .claude/skills/imagegen-frontend-web | 1 + .claude/skills/minimalist-ui | 1 + .claude/skills/stitch-design-taste | 1 + AGENTS.md | 2 +- CLAUDE.md | 2 +- scripts/generate-site-data.ts | 93 +- site/README.md | 4 +- site/api/schemas.html | 46 +- site/api/tools.html | 49 +- site/design/overview.html | 116 ++ site/{api => design}/protocol.html | 63 +- .../{internals => design}/quality-system.html | 42 +- .../request-lifecycle.html | 43 +- .../{internals => design}/server-anatomy.html | 49 +- site/{internals => design}/session-store.html | 45 +- site/guide/concepts.html | 197 --- site/guide/definitions.html | 212 +++ site/guide/getting-started.html | 115 +- site/guide/ide-setup.html | 127 -- site/guide/rationale.html | 170 --- site/guide/running-workflows.html | 165 --- site/index.html | 172 ++- site/nav.js | 20 + site/specifications.html | 152 +++ site/specs/architecture.html | 102 +- site/specs/artifact-management.html | 39 +- site/specs/checkpoints.html | 98 +- site/specs/dispatch.html | 45 +- site/specs/resource-resolution.html | 43 +- site/specs/state-management.html | 41 +- site/specs/workflow-fidelity.html | 41 +- site/specs/workflows.html | 71 +- site/style.css | 10 +- skills-lock.json | 29 + 40 files changed, 3649 insertions(+), 1341 deletions(-) create mode 100644 .agents/skills/design-taste-frontend/SKILL.md create mode 100644 .agents/skills/imagegen-frontend-web/SKILL.md create mode 100644 .agents/skills/minimalist-ui/SKILL.md create mode 100644 .agents/skills/stitch-design-taste/DESIGN.md create mode 100644 .agents/skills/stitch-design-taste/SKILL.md create mode 120000 .claude/skills/design-taste-frontend create mode 120000 .claude/skills/imagegen-frontend-web create mode 120000 .claude/skills/minimalist-ui create mode 120000 .claude/skills/stitch-design-taste create mode 100644 site/design/overview.html rename site/{api => design}/protocol.html (81%) rename site/{internals => design}/quality-system.html (90%) rename site/{internals => design}/request-lifecycle.html (90%) rename site/{internals => design}/server-anatomy.html (81%) rename site/{internals => design}/session-store.html (90%) delete mode 100644 site/guide/concepts.html create mode 100644 site/guide/definitions.html delete mode 100644 site/guide/ide-setup.html delete mode 100644 site/guide/rationale.html delete mode 100644 site/guide/running-workflows.html create mode 100644 site/nav.js create mode 100644 site/specifications.html create mode 100644 skills-lock.json diff --git a/.agents/skills/design-taste-frontend/SKILL.md b/.agents/skills/design-taste-frontend/SKILL.md new file mode 100644 index 00000000..b72132fc --- /dev/null +++ b/.agents/skills/design-taste-frontend/SKILL.md @@ -0,0 +1,1206 @@ +--- +name: design-taste-frontend +description: Anti-slop frontend skill for landing pages, portfolios, and redesigns. The agent reads the brief, infers the right design direction, and ships interfaces that do not look templated. Real design systems when applicable, audit-first on redesigns, strict pre-flight check. +--- + +# tasteskill: Anti-Slop Frontend Skill + +> Landing pages, portfolios, and redesigns. Not dashboards, not data tables, not multi-step product UI. +> Every rule below is **contextual**. None of it fires automatically. First read the brief, then pull only what fits. + +--- + +## 0. BRIEF INFERENCE (Read the Room Before Anything Else) + +Before touching code or tweaking dials, **infer what the user actually wants**. Most LLM design output is bad because the model jumps to a default aesthetic instead of reading the room. + +### 0.A Read these signals first +1. **Page kind** - landing (SaaS / consumer / agency / event), portfolio (dev / designer / creative studio), redesign (preserve vs overhaul), editorial / blog. +2. **Vibe words** the user used - "minimalist", "calm", "Linear-style", "Awwwards", "brutalist", "premium consumer", "Apple-y", "playful", "serious B2B", "editorial", "agency-y", "glassy", "dark tech". +3. **Reference signals** - URLs they linked, screenshots they pasted, products they named, brands they're competing with. +4. **Audience** - B2B procurement panel vs. design-conscious consumer vs. recruiter scanning a portfolio. The audience picks the aesthetic, not your taste. +5. **Brand assets that already exist** - logo, color, type, photography. For redesigns, these are starting material, not optional input (see Section 11). +6. **Quiet constraints** - accessibility-first audiences, public-sector, regulated industries, trust-first commerce, kids' products. These constraints OVERRIDE aesthetic preference. + +### 0.B Output a one-line "Design Read" before generating +Before any code, state in one line: **"Reading this as: \ for \, with a \ language, leaning toward \."** + +Example reads: +- *"Reading this as: B2B SaaS landing for technical buyers, with a Linear-style minimalist language, leaning toward Tailwind utilities + Geist + restrained motion."* +- *"Reading this as: solo designer portfolio for hiring managers, with an editorial / kinetic-type language, leaning toward native CSS + scroll-driven animation + custom typography."* +- *"Reading this as: redesign of a public-sector service site, with a trust-first language, leaning toward GOV.UK Frontend or USWDS."* + +### 0.C If the brief is ambiguous, ask one question, do not guess +Ask exactly **one** clarifying question - never a multi-question dump - and only when the design read genuinely diverges. Example: *"Should this feel closer to Linear-clean or Awwwards-experimental?"* + +If you can confidently infer from context, **do not ask**. Just declare the design read and proceed. + +### 0.D Anti-Default Discipline +Do not default to: AI-purple gradients, centered hero over dark mesh, three equal feature cards, generic glassmorphism on everything, infinite-loop micro-animations everywhere, Inter + slate-900. These are the LLM defaults. Reach past them deliberately based on the design read. + +--- + +## 1. THE THREE DIALS (Core Configuration) + +After the design read, set three dials. Every layout, motion, and density decision below is gated by these. + +* **`DESIGN_VARIANCE: 8`** - 1 = Perfect Symmetry, 10 = Artsy Chaos +* **`MOTION_INTENSITY: 6`** - 1 = Static, 10 = Cinematic / Physics +* **`VISUAL_DENSITY: 4`** - 1 = Art Gallery / Airy, 10 = Cockpit / Packed Data + +**Baseline:** `8 / 6 / 4`. Use these unless the design read overrides them. Do not ask the user to edit this file - overrides happen conversationally. + +### 1.A Dial Inference (design read → dial values) +| Signal | VARIANCE | MOTION | DENSITY | +|---|---|---|---| +| "minimalist / clean / calm / editorial / Linear-style" | 5-6 | 3-4 | 2-3 | +| "premium consumer / Apple-y / luxury / brand" | 7-8 | 5-7 | 3-4 | +| "playful / wild / Dribbble / Awwwards / experimental / agency" | 9-10 | 8-10 | 3-4 | +| "landing page / portfolio / marketing site (default)" | 7-9 | 6-8 | 3-5 | +| "trust-first / public-sector / regulated / accessibility-critical" | 3-4 | 2-3 | 4-5 | +| "redesign - preserve" | match existing | +1 | match existing | +| "redesign - overhaul" | +2 | +2 | match existing | + +### 1.B Use-Case Presets +| Use case | VARIANCE | MOTION | DENSITY | +|---|---|---|---| +| Landing (SaaS, mainstream) | 7 | 6 | 4 | +| Landing (Agency / creative) | 9 | 8 | 3 | +| Landing (Premium consumer) | 7 | 6 | 3 | +| Portfolio (Designer / studio) | 8 | 7 | 3 | +| Portfolio (Developer) | 6 | 5 | 4 | +| Editorial / Blog | 6 | 4 | 3 | +| Public-sector service | 3 | 2 | 5 | +| Redesign - preserve | match | match+1 | match | +| Redesign - overhaul | +2 | +2 | match | + +### 1.C How the Dials Drive Output +Use these (or user-overridden values) as global variables. Cross-references throughout this document refer to these exact variable names - never invent aliases like `LAYOUT_VARIANCE` or `ANIM_LEVEL`. + +--- + +## 2. BRIEF → DESIGN SYSTEM MAP + +Once you have the design read (Section 0) and dials (Section 1), pick the right foundation. Do not invent CSS for things that have an official package. Do not pretend an aesthetic trend is an official system. + +### 2.A When to reach for a real design system (use official packages) +| Brief reads as… | Reach for | Why | +|---|---|---| +| Microsoft / enterprise SaaS / dashboards | `@fluentui/react-components` or `@fluentui/web-components` | Official Fluent UI, Microsoft tokens, accessibility done | +| Google-ish UI, Material-flavored product | `@material/web` + Material 3 tokens | Official, theme-able via Material Theming | +| IBM-style B2B / enterprise analytics | `@carbon/react` + `@carbon/styles` | Official Carbon, mature data-density patterns | +| Shopify app surfaces | `polaris.js` web components / Polaris React | Required for Shopify admin UI | +| Atlassian / Jira-style product | `@atlaskit/*` + `@atlaskit/tokens` | Official Atlassian DS | +| GitHub-style devtool / community page | `@primer/css` or `@primer/react-brand` | Official Primer; Brand variant for marketing | +| Public-sector UK service | `govuk-frontend` | Legally / regulatorily expected | +| US public-sector / trust-first | `uswds` | Same | +| Fast local-business / agency MVP | Bootstrap 5.3 | Boring, fast, works | +| Modern accessible React foundation | `@radix-ui/themes` | Primitives + polished theme | +| Modern SaaS where you own the components | shadcn/ui (`npx shadcn@latest add ...`) | You own the code, easy to customise; never ship default state | +| Tailwind-based modern SaaS / AI marketing | Tailwind v4 utilities + `dark:` variant | Default for indie + small team builds | + +**Honesty rule:** if the brief reads as one of the systems above, install and use the **official** package. Do not recreate its CSS by hand. Do not import a system's tokens but then override 90% of them. + +**One system per project.** Do not mix Fluent React with Carbon in the same tree. Do not import shadcn/ui components into a Material 3 app. + +### 2.B When the brief is an aesthetic, not a system +For these directions, there is **no single official package**. Build with native CSS + Tailwind + a maintained component library. Be honest in code comments about what is borrowed inspiration vs. official material. + +| Aesthetic | Honest implementation | +|---|---| +| Glassmorphism / "frosted glass" | `backdrop-filter`, layered borders, highlight overlays. Provide solid-fill fallback for `prefers-reduced-transparency`. | +| Bento (Apple-style tile grids) | CSS Grid with mixed cell sizes. No single library owns this. | +| Brutalism | Native CSS, monospace, raw borders. No library. | +| Editorial / magazine | Serif type, asymmetric grid, generous whitespace. No library. | +| Dark tech / hacker | Mono + accent neon, terminal motifs. No library. | +| Aurora / mesh gradients | SVG or layered radial gradients. No library. | +| Kinetic typography | Native CSS animations, scroll-driven animations, GSAP for hijacks. No library. | +| **Apple Liquid Glass** | Apple documents this for Apple platforms only. **There is no official `liquid-glass.css`.** Web implementations are approximations using `backdrop-filter` + layered borders + highlights. Label clearly as approximation. | + +--- + +## 3. DEFAULT ARCHITECTURE & CONVENTIONS + +Unless the design read picks a real design system (Section 2.A), these are the defaults: + +### 3.A Stack +* **Framework:** React or Next.js. Default to Server Components (RSC). + * **RSC SAFETY:** Global state works ONLY in Client Components. In Next.js, wrap providers in a `"use client"` component. + * **INTERACTIVITY ISOLATION:** Any component using Motion, scroll listeners, or pointer physics MUST be an isolated leaf with `'use client'` at the top. Server Components render static layouts only. +* **Styling:** **Tailwind v4** (default). Tailwind v3 only if the existing project demands it. + * For v4: do NOT use `tailwindcss` plugin in `postcss.config.js`. Use `@tailwindcss/postcss` or the Vite plugin. +* **Animation:** **Motion** (the library formerly known as Framer Motion). Import from `motion/react` (`import { motion } from "motion/react"`). The `framer-motion` package still works as a legacy alias - prefer `motion/react` in new code. +* **Fonts:** Always use `next/font` (Next.js) or self-host with `@font-face` + `font-display: swap`. Never link Google Fonts via `` in production. + +### 3.B State +* Local `useState` / `useReducer` for isolated UI. +* Global state ONLY for deep prop-drilling avoidance - Zustand, Jotai, or React context. +* **NEVER** use `useState` to track continuous values driven by user input (mouse position, scroll progress, pointer physics, magnetic hover). Use Motion's `useMotionValue` / `useTransform` / `useScroll`. `useState` re-renders the React tree on every change and collapses on mobile. + +### 3.C Icons +* **Allowed libraries (priority order):** `@phosphor-icons/react`, `hugeicons-react`, `@radix-ui/react-icons`, `@tabler/icons-react`. +* **Discouraged:** `lucide-react`. Acceptable only when the user explicitly asks for it or the project already depends on it. +* **NEVER hand-roll SVG icons.** If a glyph is missing, install a second library or compose from primitives - do not draw icon paths from scratch. +* **One family per project.** Do not mix Phosphor with Lucide in the same component tree. +* **Standardize `strokeWidth` globally** (e.g. `1.5` or `2.0`). + +### 3.D Emoji Policy +Discouraged by default in code, markup, and visible text. Replace symbols with icon-library glyphs. **Override:** allow emojis only when the user explicitly asks for a playful / chat-style / social-native vibe - and even then use them sparingly with intent. + +### 3.E Responsiveness & Layout Mechanics +* Standardize breakpoints (`sm 640`, `md 768`, `lg 1024`, `xl 1280`, `2xl 1536`). +* Contain page layouts using `max-w-[1400px] mx-auto` or `max-w-7xl`. +* **Viewport Stability:** NEVER use `h-screen` for full-height Hero sections. ALWAYS use `min-h-[100dvh]` to prevent layout jumping on mobile (iOS Safari address bar). +* **Grid over Flex-Math:** NEVER use complex flexbox percentage math (`w-[calc(33%-1rem)]`). ALWAYS use CSS Grid (`grid grid-cols-1 md:grid-cols-3 gap-6`). + +### 3.F Dependency Verification (mandatory) +Before importing ANY 3rd-party library, check `package.json`. If the package is missing, output the install command first. **Never** assume a library exists. + +--- + +## 4. DESIGN ENGINEERING DIRECTIVES (Bias Correction) + +LLMs default to clichés. Override these defaults proactively. Each rule has a context-aware override path. + +### 4.1 Typography +* **Display / Headlines:** Default `text-4xl md:text-6xl tracking-tighter leading-none`. +* **Body / Paragraphs:** Default `text-base text-gray-600 leading-relaxed max-w-[65ch]`. +* **Sans font choice:** + * **Discouraged as default:** `Inter`. Pick `Geist`, `Outfit`, `Cabinet Grotesk`, `Satoshi`, or a brand-appropriate serif first. + * **Override:** Inter is acceptable when the user explicitly asks for a neutral / standard / Linear-style feel, or when the brief is a public-sector / accessibility-first site. +* **Pairings to know:** `Geist` + `Geist Mono`, `Satoshi` + `JetBrains Mono`, `Cabinet Grotesk` + `Inter Tight`, `GT America` + `IBM Plex Mono`. + +* **SERIF DISCIPLINE (VERY DISCOURAGED AS DEFAULT):** + * Serif is **very discouraged as the default font for any project.** "It feels creative / premium / editorial" is NOT a reason to reach for serif. The agent's default mental model that "creative brief = serif" is the single most-tested AI tell in production rounds. + * **Serif is only acceptable when ONE of these is explicitly true:** + - The brand brief literally names a serif font, OR + - The aesthetic family is genuinely editorial / luxury / publication / manuscript / heritage / vintage AND you can articulate why this specific serif fits this specific brand + * For everything else (creative agency, design studio, modern brand, premium consumer, portfolio, lifestyle), **default sans-serif display** (Geist Display, ABC Diatype, Söhne Breit, Cabinet Grotesk Display, Migra Sans, GT Walsheim, Inter Display, PP Neue Montreal). Sans display fonts are not "boring" — they are the default for the same reason black is the default in fashion. + * **EMPHASIS RULE (related):** When you want to emphasize a word within a headline (the kinetic "and `spatial` design" type move), use **italic or bold of the SAME font**. Do NOT inject a random serif word into a sans headline (or vice versa) just to add visual interest. Mixed-family emphasis is amateur. Italic/bold emphasis in the same family is the right move. + * **Specifically BANNED as defaults:** `Fraunces` and `Instrument_Serif` (the two LLM-favorite display serifs). + * **If a serif is justified** (rare, per the above), rotate from this pool, do NOT reuse the same serif across consecutive projects: PP Editorial New, GT Sectra Display, Cardinal Grotesque, Reckless Neue, Tiempos Headline, Recoleta, Cormorant Garamond, Playfair Display, EB Garamond, IvyPresto, Migra, Editorial Old, Saol Display, Söhne Breit Kursiv, Domaine Display, Canela, Schnyder, Tobias, NB Architekt, ITC Galliard. + +* **ITALIC DESCENDER CLEARANCE (mandatory):** When italic is used in display type and the word contains a descender letter (`y g j p q`), `leading-[1]` or `leading-none` will clip the descender. Use `leading-[1.1]` minimum and add `pb-1` or `mb-1` reserve on the wrapping element. Audit every italic word in display headlines before shipping. + +### 4.2 Color Calibration +* Max 1 accent color. Saturation < 80% by default. +* **THE LILA RULE:** The "AI Purple / Blue glow" aesthetic is discouraged as a default. No automatic purple button glows, no random neon gradients. Use neutral bases (Zinc / Slate / Stone) with high-contrast singular accents (Emerald, Electric Blue, Deep Rose, Burnt Orange, etc.). +* **Override:** if the brand or brief explicitly asks for purple / violet / lila, embrace it. But execute with intent: consistent palette, harmonised neutrals, restrained gradients. Not generic AI gradient slop. +* **One palette per project.** Do not fluctuate between warm and cool grays within the same project. +* **COLOR CONSISTENCY LOCK (mandatory):** Once an accent color is chosen for a page, it is used on the WHOLE page. A warm-grey site does not suddenly get a blue CTA in section 7. A rose-accented site does not get a teal status badge in the footer. Pick one accent, lock it, audit every component before shipping. + +* **PREMIUM-CONSUMER PALETTE BAN (mandatory, second-most-recurring AI-tell):** + * For premium-consumer briefs (cookware, wellness, artisan, luxury, heritage craft, DTC home goods, etc.) the LLM default is **warm beige/cream + brass/clay/oxblood/ochre + espresso/ink dark text**. Concretely banned hex families as default backgrounds and accents: + - Backgrounds: `#f5f1ea`, `#f7f5f1`, `#fbf8f1`, `#efeae0`, `#ece6db`, `#faf7f1`, `#e8dfcb` (all "warm paper / cream / chalk / bone") + - Accents: `#b08947`, `#b6553a`, `#9a2436`, `#9c6e2a`, `#bc7c3a`, `#7d5621` (all "brass / clay / oxblood / ochre") + - Text: `#1a1714`, `#1a1814`, `#1b1814` (all "espresso / warm near-black") + * This palette is BANNED as the default reach for premium-consumer briefs. Every premium-consumer site you have ever shipped uses this exact palette. The brand becomes invisible. + * **Default alternatives (rotate, do not reuse):** + - **Cold Luxury:** silver-grey + chrome + smoke (think Tesla, Apple Watch Hermes-without-the-leather) + - **Forest:** deep green + bone + amber accent (think Filson, Patagonia premium) + - **Black and Tan:** true off-black + warm tan, sharp contrast, no beige + - **Cobalt + Cream:** saturated blue against a single neutral, no brass + - **Terracotta + Slate:** warm rust against cool grey, no brass + - **Olive + Brick + Paper:** muted olive plus brick-red accent + - **Pure monochrome + single saturated pop:** off-white + off-black + one bright accent (electric blue, emerald, hot pink, etc.) + * **Palette-rotation rule:** if the previous premium-consumer project you generated used the beige+brass family, this one MUST use a different family. Do not ship the same warm-craft palette twice in a row. + * **Override:** the beige+brass+espresso palette is acceptable ONLY when the brand brief explicitly names those colors, or when the brand identity is genuinely vintage / artisan / warm-craft AND you can articulate why this specific palette fits this specific brand. Default-reaching for it because "this is a cookware brief" is banned. + +### 4.3 Layout Diversification +* **ANTI-CENTER BIAS:** Centered Hero / H1 sections are avoided when `DESIGN_VARIANCE > 4`. Force "Split Screen" (50/50), "Left-aligned content / right-aligned asset", "Asymmetric white-space", or scroll-pinned structures. +* **Override:** centered hero is OK for editorial / manifesto / launch-announcement briefs where the message itself is the design. + +### 4.4 Materiality, Shadows, Cards +* Use cards ONLY when elevation communicates real hierarchy. Otherwise group with `border-t`, `divide-y`, or negative space. +* When a shadow is used, tint it to the background hue. No pure-black drop shadows on light backgrounds. +* For `VISUAL_DENSITY > 7`: generic card containers are banned. Data metrics breathe in plain layout. +* **SHAPE CONSISTENCY LOCK (mandatory):** Pick ONE corner-radius scale for the page and stick to it. Options: all-sharp (radius 0), all-soft (radius 12-16px), all-pill (full radius for interactive). Mixed systems are allowed only when there is a documented rule (e.g. "buttons are full-pill, cards are 16px, inputs are 8px") and that rule is followed everywhere. Round buttons in a square layout, or square cards on a pill-button page, is broken design. + +### 4.5 Interactive UI States +LLMs default to "static successful state only." Always implement full cycles: +* **Loading:** Skeletal loaders matching the final layout's shape. Avoid generic circular spinners. +* **Empty States:** Beautifully composed; indicate how to populate. +* **Error States:** Clear, inline (forms), or contextual (toasts only for transient). +* **Tactile Feedback:** On `:active`, use `-translate-y-[1px]` or `scale-[0.98]` to simulate a physical push. +* **BUTTON CONTRAST CHECK (mandatory, a11y):** Before shipping any button, verify the button text is readable against the button background. White button + white text, `bg-white` CTA with `text-white` label, transparent button against the page background with no border → all banned. Audit every CTA: contrast ratio WCAG AA min (4.5:1 for body, 3:1 for large text 18px+). Same rule applies to ghost buttons over photographic backgrounds (use a backdrop, scrim, or stroke). +* **CTA BUTTON WRAP BAN (mandatory):** Button text MUST fit on one line at desktop. If a label like "VIEW SELECTED WORK" wraps to 2 or 3 lines, the button is broken. Fix by EITHER shortening the label (3 words max for primary CTAs, ideally 1-2) OR widening the button (do not artificially constrain `max-width` on CTAs). Wrapped CTAs at desktop are a Pre-Flight Fail. +* **NO DUPLICATE CTA INTENT (mandatory):** Two CTAs with the same intent on one page is a Pre-Flight Fail. Examples of same intent: "Get in touch" + "Contact us" + "Let's talk" + "Start a project" + "Start something" + "Reach out" = all "contact" intent → pick ONE label and use it everywhere on the page (nav, hero, footer). Same for "Try free" + "Get started" + "Sign up free" (all "signup" intent) and "View work" + "See selected work" + "Browse projects" (all "portfolio" intent). One label per intent. +* **FORM CONTRAST CHECK (mandatory, a11y):** Form inputs, placeholder text, focus rings, helper text, and error text all pass WCAG AA contrast against the section background. Light placeholders on a near-white form, white form on white page section, form labels grayer than 4.5:1 contrast → all banned. Audit every form before shipping. + +### 4.6 Data & Form Patterns +* Label ABOVE input. Helper text optional but present in markup. Error text BELOW input. Standard `gap-2` for input blocks. +* No placeholder-as-label. Ever. + +### 4.7 Layout Discipline (Hard Rules. Failing any of these is shipping broken work) + +* **Hero MUST fit in the initial viewport.** Headline max 2 lines on desktop, subtext max **20 words** AND max 3-4 lines, CTAs visible without scroll. If the copy is too long: reduce font scale OR cut copy. If you cannot describe the value-prop in 20 words of subtext, the value-prop is unclear, not the rule too tight. Never let the hero overflow and force scroll to find the CTA. +* **Hero font-scale discipline.** Plan font size and image size *together*. If the hero asset is large and the headline is more than 6 words, do not start at `text-7xl/text-8xl`. Default sensible range: `text-4xl md:text-5xl lg:text-6xl` for most heroes; `text-6xl md:text-7xl` only when the headline is 3-5 words. A 4-line hero headline is always a font-size error, never a copy-length error. +* **HERO TOP PADDING CAP (mandatory):** Hero top padding max `pt-24` (≈6rem) at desktop. More than that means the hero content floats halfway down the viewport and reads as a layout bug, not as intentional space. If your hero needs more breathing room, increase font scale or asset size, not top padding. +* **HERO STACK DISCIPLINE (max 4 text elements).** The hero is a single moment, not a feature list. Allowed text elements, max 4 in total: + 1. Eyebrow (small uppercase label) OR brand strip OR neither - pick zero or one + 2. Headline (max 2 lines, see above) + 3. Subtext (max 20 words, max 4 lines) + 4. CTAs (1 primary + max 1 secondary) + - **BANNED in the hero:** tiny tagline below CTAs ("Works with GitHub, GitLab, and self-hosted Git"), trust micro-strip ("Used by engineering teams at..."), pricing teaser ("Free for solo, $10/user for teams"), feature bullet list, social-proof avatar row. All of those move to dedicated sections directly below the hero. + - If you have an eyebrow AND a tagline below CTAs in the same hero, drop the tagline. If you have a brand strip AND a tagline, drop the tagline. One small text element per hero, max. +* **"Used by" / "Trusted by" logo wall belongs UNDER the hero, never inside it.** The hero is for the value prop and primary CTA. The logo wall is a separate section directly below. Do not stuff trust logos into the same flex row as the hero copy. +* **Navigation MUST render on a single line on desktop.** If items don't fit at `lg` (1024px), condense labels, drop secondary items, or move to a hamburger. A two-line nav at desktop is broken design. +* **Navigation height cap: 80px max desktop, default 64-72px.** No huge "agency" nav bars that eat 15% of the viewport. +* **Bento grids MUST have rhythm, not one-sided repetition.** Do not stack 6 left-image / right-text rows. Vary the composition: alternate full-width feature rows, asymmetric tile sizes, vertical breaks. +* **BENTO CELL COUNT RULE (mandatory):** A bento grid has EXACTLY as many cells as you have content for. 3 items → 3 cells (1+2 split, or 2+1, or asymmetric trio). 5 items → 5 cells (2+3, 3+2, hero+4, etc.). If your grid has an empty cell in the middle or at the end, you planned wrong. Re-shape the grid; do not paste a blank tile. +* **Section-Layout-Repetition Ban.** Once you use a layout family for a section (e.g., 3-column-image-cards, full-width-quote, split-text-image), that family can appear at most ONCE on the page. "Selected commissions" must not look like "What we do." A landing page with 8 sections must use at least 4 different layout families. +* **ZIGZAG ALTERNATION CAP (mandatory).** Alternating "left-image + right-text" then "left-text + right-image" zigzag layout = banal. Max 2 sections in a row with this image+text-split pattern. The 3rd consecutive image+text split is a Pre-Flight Fail. Break the pattern with a full-width section, a vertical-stack section, a bento grid, a marquee, or a different layout family. +* **EYEBROW RESTRAINT (mandatory, the #1 violated rule in production tests).** An "eyebrow" is the small uppercase wide-tracking label sitting above a section headline (e.g. `FOUR COLORWAYS`, `SELECTED WORK`, `THE HARDWARE`, `Git-native task management`). Typical CSS signature: `text-[11px] uppercase tracking-[0.18em]`, `font-mono text-[10.5px] uppercase tracking-[0.22em]`. Every AI-built site puts an eyebrow above EVERY section header, producing the same templated rhythm. Hard rule: + - **Maximum 1 eyebrow per 3 sections.** Hero counts as 1. So a page with 9 sections may use at most 3 eyebrows total. + - If section A has an eyebrow, the next 2 sections cannot have one. + - **Pre-Flight Check is mechanical:** count instances of `uppercase tracking` (or similar small-caps mono labels above headlines) across all section components. If count > ceil(sectionCount / 3), the output fails. + - **What to do instead of an eyebrow:** drop it entirely. The headline alone is enough. If you need to categorize a section, the section's location on the page already categorizes it; no label needed. +* **SPLIT-HEADER BAN (mandatory).** The pattern "left big headline + right small explainer paragraph" as a section header (left col-span-7/8, right col-span-4/5 with a small body paragraph floating in the right column) is **banned as default**. Sections should have ONE focused message. If you genuinely need both a headline and an explainer paragraph, stack them vertically (headline on top, body below, max-width 65ch). Reach for the split-header pattern only when there is a real compositional reason (e.g., the right column carries a visual or interactive element, not just filler text). +* **Bento Background Diversity (mandatory).** Bento and feature-grid sections cannot be 6 white-on-white cards with text inside. At least 2-3 cells in any multi-cell grid need real visual variation: a real image, a brand-appropriate gradient (not AI-purple), a pattern, a tinted background. A cream-on-cream bento with only typography inside reads as boring AI default, even when the rest of the page is good. +* **Mobile collapse must be explicit per section.** For every multi-column layout, declare the `< 768px` fallback in the same component. No "it'll work, Tailwind handles it" assumptions. + +### 4.8 Image & Visual Asset Strategy + +Landing pages and portfolios are **visual products**. Text-only pages with fake-screenshot divs are slop. + +**Priority order for visual assets:** +1. **Image-generation tool first.** If ANY image-gen tool is available in the environment (`generate_image`, MCP image tool, IDE-integrated gen, OpenAI image tools, etc.) you MUST use it to create section-specific assets: hero photography, product shots, texture backgrounds, mood images. Generate at the right aspect ratio for the section. Do not skip this step because hand-rolled CSS feels faster. +2. **Real web images second.** When no gen tool is available, use real photography sources. Acceptable defaults: + * `https://picsum.photos/seed/{descriptive-seed}/{w}/{h}` for placeholder photography (seed should describe the section, e.g. `marrow-cookware-kitchen`) + * Actual stock or brand URLs when the brief provides them + * Open-license sources (Unsplash via direct URL, Pexels) if explicitly allowed +3. **Last resort: tell the user.** If neither is possible, do NOT fill the page with hand-rolled SVG illustrations or div-based "fake screenshots." Instead, leave clearly-labeled placeholder slots (``) and at the end of the response say: *"This page needs real images at: \[list of placements\]. Please generate or provide them."* + +**Even minimalist sites need real images.** A pure-text page is not minimalism. It is incomplete work. Even an editorial Linear-style site needs at least 2-3 real images (hero, one product/lifestyle shot, one supporting image). Generate B&W minimalist photography if the brief is restrained; do not skip images entirely because the dial is low. + +**Real company logos for social proof.** When the brief calls for a "Trusted by / Used by / Customers" logo wall, do NOT default to plain text wordmarks (`Acme Co` styled in a row). Use real SVG logos: +* **Source: Simple Icons** (`https://cdn.simpleicons.org/{slug}/ffffff` for any color, or `simple-icons` npm package). Covers most known brands. +* **Alternative: devicon** for tech-stack logos (`@svgr/cli` or CDN). +* **Make-up the brand name? Then make-up an SVG mark too.** Generate a simple monogram (one letter in a circle, two-letter ligature, abstract glyph) rendered as an inline `` matching the page style. Plain text wordmarks for invented brand names look generic. +* **Always** ensure logos render in both light and dark mode (white-on-dark, black-on-light, or single-color theme variable). +* **LOGO-ONLY rule (mandatory):** logo wall = logos and nothing else. Do NOT print industry / category labels below each logo (no `Vercel` + `hosting` underneath, no `Stripe` + `payments`, no `Cloudflare` + `infra`). The logo is the credibility, the label adds nothing the user does not already know. Optional: brand name as alt-text for screen readers, optional link to the brand's site. That is it. + +**Hand-rolled illustrations:** +* SVG icons from libraries: fine (see Section 3.C). +* Hand-rolled decorative SVGs (custom illustrations, logos, marks): **strongly discouraged**, never as default. Acceptable only when: + - The brief explicitly calls for it ("draw me an SVG logo") + - It's a single, simple geometric mark (a square, a circle, a wordmark in display type) + - You're confident in the output quality + +**Div-based fake screenshots are banned.** A "hand-built product preview" rendered with `
    ` rectangles, fake task lists, fake dashboards, fake terminal windows is a Tell. If you need to show a product: +* Use a real screenshot URL if one exists +* Generate one via image tool +* Use a real component preview (an actual mini-version of the UI inside the page) +* Or skip the preview entirely and use editorial photography + +**Hero needs a real visual.** Text + gradient blob is not a hero - it's a placeholder. + +### 4.9 Content Density + +Landing pages live on the **first impression**, not the full read. Cut ruthlessly. + +* **Default content shape per section:** short headline (≤ 8 words) + short sub-paragraph (≤ 25 words) + one visual asset OR one CTA. Anything more must be justified by the section's job. +* **No data-dump sections.** A 20-row publication table, a 30-row award list, a giant pricing matrix on a marketing page = wrong layout. Use: + - Top 3-5 highlights + "View full list" link + - Marquee / carousel for breadth + - Different page entirely if the data is the product +* **Long lists need a different UI component, not a longer list.** Default `
      ` with bullets / `divide-y` rows is the lazy choice. If you have > 5 items, reach for one of these instead: + - 2-column split with grouped items + - Card grid with image + label per item + - Tabs / accordion if items are categorisable + - Horizontal scroll-snap pills + - Carousel for breadth-heavy lists (testimonials, logos, capabilities) + - Marquee for "lots-of-things-that-don't-need-individual-attention" + A spec sheet with 10 rows + a hairline under every row is the WORST default. Either group rows into 2-3 chunks with sparse dividers, or move to a card-per-spec layout. +* **Spec sheets specifically (the Marrow-cookware pattern).** A long product specification table with `border-b` on every row is the AI default for cookware / hardware / apparel / artisan-goods briefs. Banned. Concrete alternatives: + - **2-col card grid:** each spec gets its own card with the spec name, the value (large display number), and a one-line "why it matters" body. Cards arranged 2-col on desktop, 1-col mobile. + - **Scroll-snap horizontal pills:** each spec is a pill, user can flick through. + - **Grouped chunks:** group 10 specs into 3 logical clusters (e.g. "Materials", "Cooking", "Warranty"), each cluster gets ONE soft divider and a cluster heading. + - **Featured-vs-rest:** 3-4 hero specs visualised as large display tiles, the rest collapsed under a "View full specifications" disclosure. + +* **COPY SELF-AUDIT (mandatory before ship):** Before declaring any task done, re-read every visible string on the page (headlines, subheads, eyebrows, button labels, body copy, captions, alt text, footer text, error messages). Flag any string that is: + - **Grammatically broken** ("free on its past", "two plans but one is honest", "to put it on the table" out of context) + - **Has unclear referents** ("we plan to stay that way" without prior context) + - **Sounds like AI hallucination** (cute-but-wrong wordplay, forced metaphors that don't track, "elegant nothing" phrases) + - **Reads like an LLM trying to sound thoughtful** (passive-aggressive humility, fake-craftsman labels, mock-poetic micro-meta) + Rewrite every flagged string. If unsure whether a string makes sense, replace it with a plain functional sentence. AI-generated cute copy is worse than boring copy. +* **Fake-precise numbers are flagged.** Numbers like `92%`, `4.1×`, `48k`, `5.8 mm`, `13.4 lb` either: + - Come from real data (brief, brand guidelines, public metrics) - fine + - Are explicitly labeled as mock (``, "example", "sample data") - fine + - Are AI-invented spec aesthetics - banned. Don't fake engineering precision the brand doesn't claim. +* **One copy register per page.** Don't mix technical mono ("47 tasks · 0.6 ctx-switches/day"), editorial prose, and marketing punch in the same composition unless the brand voice explicitly calls for it. + +### 4.10 Quotes & Testimonials + +* **Max 3 lines** of quote body. Never 6. If the original quote is longer → cut it. A landing-page quote is a snippet, not the full review. +* For very small font sizes (e.g. footer-style testimonials), the line cap can stretch slightly. Spirit: "fits in a glance." +* **No em-dashes inside the quote text** as design flourish (long pauses, kinetic em-dashes, em-dash-bullets). See Section 9.G - em-dash is completely banned. +* Attribution: name + role + (optionally) company. Never name only ("- Sarah"). +* Quote marks: use real typographic quotes ( " " ) or none at all. Not straight ASCII ( " ). + +### 4.11 Page Theme Lock (Light / Dark Mode Consistency) + +The page has ONE theme. Sections do not invert. + +* If the page is dark mode, ALL sections are dark mode. No light-mode-warm-paper section sandwiched between dark sections (or vice versa). The user must not feel they walked into a different website mid-scroll. +* The exception: if the brief explicitly calls for a "Color Block Story" or "Theme Switch on Scroll" device AND that is a deliberate composition (one full theme switch with a strong transition, not random alternation), it is allowed once per page. +* Default behaviour: pick light, dark, or auto (`prefers-color-scheme`) at the page level and lock it. Section-level background tints within the same theme family are fine (`bg-zinc-950` next to `bg-zinc-900`); flipping to `bg-amber-50` in the middle of a `bg-zinc-950` page is broken. +* When using a design system with built-in theming (Radix Themes, shadcn/ui with ``), set the theme ONCE in `layout.tsx` or the page root. Do not let individual sections override. + +--- + +## 5. CONTEXT-AWARE PROACTIVITY + +These are tools, not defaults. Use them when the design read calls for them. **None of these fire automatically.** + +* **Liquid Glass / Glassmorphism:** Appropriate for premium consumer, Apple-adjacent, luxury brand, or media-overlay vibes. Inappropriate for dashboards, public-sector, or "boring B2B." When used, go beyond `backdrop-blur`: add a 1px inner border (`border-white/10`) and a subtle inner shadow (`shadow-[inset_0_1px_0_rgba(255,255,255,0.1)]`) for physical edge refraction. Provide a solid-fill fallback under `prefers-reduced-transparency`. +* **Magnetic Micro-physics:** Use when `MOTION_INTENSITY > 5` AND the brief reads premium / playful / agency. Implement EXCLUSIVELY with Motion's `useMotionValue` / `useTransform` outside the React render cycle. Never `useState`. See Section 3.B. +* **Perpetual Micro-Interactions** (Pulse, Typewriter, Float, Shimmer, Carousel): Use when `MOTION_INTENSITY > 5` AND the section actively benefits from motion (status indicators, live feeds, AI-feel). **Not every card needs an infinite loop.** If a section is informational, leave it still. Apply Spring Physics (`type: "spring", stiffness: 100, damping: 20`) - no linear easing. +* **"Motion claimed, motion shown."** If `MOTION_INTENSITY > 4`, the page must actually move: entry transitions on hero, scroll-reveal on key sections, hover physics on CTAs, at minimum. A static page that claims `MOTION_INTENSITY: 7` is broken. Conversely, if you cannot ship working motion in the available scope, drop the dial to 3 and ship a clean static page. Never half-build motion that breaks (cut-off ScrollTriggers, jumpy enters, missing cleanups). +* **MOTION MUST BE MOTIVATED (mandatory).** Before adding any animation, ask: "what does this animation communicate?" Valid answers: hierarchy (drawing attention to the right thing), storytelling (revealing content in sequence that matches a narrative), feedback (acknowledging a user action), state transition (showing something changed). Invalid answer: "it looked cool". GSAP everywhere because GSAP is available is amateur. Each ScrollTrigger, each marquee, each pinned section needs a reason. If you cannot articulate the reason in one sentence, drop the animation. +* **MARQUEE MAX-ONE-PER-PAGE (mandatory).** Horizontal scrolling text marquees ("logos endlessly scrolling", "manifesto scrolling sideways", "kinetic word strip") are appropriate at most ONCE per page. Two or more marquees on the same page reads as lazy filler. Pick the one section where the marquee actually serves the content; the others get a different layout. +* **GSAP Sticky-Stack Pattern (when scroll-stack is used).** A "card stack on scroll" must be a REAL sticky-stack, not a sequential reveal list. See Section 5.A below for the canonical code skeleton. Common failure: trigger fires halfway through scroll instead of pinning at viewport top. Fix: `start: "top top"` not `start: "top center"` or `"top 80%"`. +* **GSAP Horizontal-Pan Pattern (when horizontal scroll-hijack is used).** See Section 5.B below for the canonical skeleton. Common failure: animation starts before the section is pinned, so the user sees half a slide. Same fix: `start: "top top"`, pin the wrapper, scrub the inner track. + +### 5.A Sticky-Stack - Canonical Skeleton + +```tsx +"use client"; +import { useRef, useEffect } from "react"; +import { gsap } from "gsap"; +import { ScrollTrigger } from "gsap/ScrollTrigger"; +import { useReducedMotion } from "motion/react"; + +gsap.registerPlugin(ScrollTrigger); + +export function StickyStack({ cards }: { cards: React.ReactNode[] }) { + const ref = useRef(null); + const reduce = useReducedMotion(); + + useEffect(() => { + if (reduce || !ref.current) return; + const ctx = gsap.context(() => { + const cardEls = gsap.utils.toArray(".stack-card"); + cardEls.forEach((card, i) => { + if (i === cardEls.length - 1) return; + ScrollTrigger.create({ + trigger: card, + start: "top top", // pin at viewport top + endTrigger: cardEls[cardEls.length - 1], + end: "top top", + pin: true, + pinSpacing: false, + }); + gsap.to(card, { + scale: 0.92, + opacity: 0.55, + ease: "none", + scrollTrigger: { + trigger: cardEls[i + 1], + start: "top bottom", + end: "top top", + scrub: true, + }, + }); + }); + }, ref); + return () => ctx.revert(); + }, [reduce]); + + return ( +
      + {cards.map((card, i) => ( +
      + {card} +
      + ))} +
      + ); +} +``` + +Critical points: `start: "top top"`, `pin: true`, every card except the last is pinned, the scale/opacity transform is driven by the NEXT card's scroll trigger (so previous card shrinks as next one arrives). + +### 5.B Horizontal-Pan - Canonical Skeleton + +```tsx +"use client"; +import { useRef, useEffect } from "react"; +import { gsap } from "gsap"; +import { ScrollTrigger } from "gsap/ScrollTrigger"; +import { useReducedMotion } from "motion/react"; + +gsap.registerPlugin(ScrollTrigger); + +export function HorizontalPan({ children }: { children: React.ReactNode }) { + const wrap = useRef(null); + const track = useRef(null); + const reduce = useReducedMotion(); + + useEffect(() => { + if (reduce || !wrap.current || !track.current) return; + const ctx = gsap.context(() => { + const distance = track.current!.scrollWidth - window.innerWidth; + gsap.to(track.current, { + x: -distance, + ease: "none", + scrollTrigger: { + trigger: wrap.current, + start: "top top", // pin starts when section top hits viewport top + end: () => `+=${distance}`, // scroll distance = track width minus viewport + pin: true, + scrub: 1, + invalidateOnRefresh: true, + }, + }); + }, wrap); + return () => ctx.revert(); + }, [reduce]); + + return ( +
      +
      + {children} +
      +
      + ); +} +``` + +Critical points: `start: "top top"`, `pin: true`, `end: "+=${distance}"` (scroll length = horizontal travel needed), `scrub: 1`. The wrapper is pinned, the inner track slides horizontally as the user scrolls vertically. + +### 5.C Scroll-Reveal Stagger - Canonical Skeleton (lighter alternative) + +For simple "items appear as they enter viewport" (no pinning), prefer Motion's `whileInView` over GSAP - lighter, no ScrollTrigger needed: + +```tsx +"use client"; +import { motion, useReducedMotion } from "motion/react"; + +export function RevealStagger({ items }: { items: string[] }) { + const reduce = useReducedMotion(); + return ( +
        + {items.map((item, i) => ( + + {item} + + ))} +
      + ); +} +``` + +Use this for: feature lists, testimonial grids, logo walls, anything that just needs "enter on scroll." Save GSAP for actual pin/scrub work. + +### 5.D Forbidden Animation Patterns + +* **`window.addEventListener("scroll", ...)`** is banned. It runs on every scroll frame, jank-prone, no batching. Use Motion's `useScroll()`, GSAP's `ScrollTrigger`, IntersectionObserver, or CSS `scroll-driven animations` (`animation-timeline: view()`). +* **Custom scroll progress calculations using `window.scrollY`** in React state. Same reason. Re-renders on every frame. +* **`requestAnimationFrame` loops that touch React state.** Use motion values (`useMotionValue` + `useTransform`) instead. +* **Layout Transitions:** Use Motion's `layout` and `layoutId` props for visible state changes (re-ordering lists, expanding modals, shared elements between routes). Do not wrap static content in `layout` props "for safety" - it costs measurement work. +* **Staggered Orchestration:** Use `staggerChildren` (Motion) or CSS cascade (`animation-delay: calc(var(--index) * 100ms)`) for reveal moments where sequence matters. For `staggerChildren`, parent (`variants`) and children MUST share the same Client Component tree. + +--- + +## 6. PERFORMANCE & ACCESSIBILITY GUARDRAILS + +### 6.A Hardware Acceleration +* Animate ONLY `transform` and `opacity`. Never animate `top`, `left`, `width`, `height`. +* Use `will-change: transform` sparingly - only on elements that will actually animate. + +### 6.B Reduced Motion (mandatory) +* **Any motion above `MOTION_INTENSITY > 3` MUST honor `prefers-reduced-motion`.** This is non-negotiable. +* In Motion: wrap with `useReducedMotion()` and degrade to static. +* In CSS: gate animations behind `@media (prefers-reduced-motion: no-preference)` or provide an override block under `@media (prefers-reduced-motion: reduce)` that disables. +* Infinite loops, parallax, scroll-hijack, and magnetic physics MUST collapse to static / instant under reduced motion. + +### 6.C Dark Mode (mandatory for any consumer-facing page) +* Design for **both modes from the start**. Never ship light-only or dark-only without explicit user instruction. +* Use Tailwind `dark:` variant OR CSS variables for tokens. Pick one strategy per project. +* **Do not prescribe specific dark-mode colors here.** The brief decides. Maintain visual hierarchy, brand identity, and WCAG AA contrast (AAA for body) across both modes. +* Respect `prefers-color-scheme: dark`. Default to system preference unless the brand insists on one mode. + +### 6.D Core Web Vitals Targets +* **LCP** < 2.5s. Hero image must be `next/image priority` or preloaded. +* **INP** < 200ms. Heavy work off main thread. +* **CLS** < 0.1. Reserve space for images, fonts, embeds. +* Run Lighthouse before declaring a page done. + +### 6.E DOM Cost +* Apply grain / noise filters EXCLUSIVELY to fixed, `pointer-events-none` pseudo-elements (e.g., `fixed inset-0 z-[60] pointer-events-none`). NEVER on scrolling containers - continuous GPU repaints destroy mobile FPS. +* Be aware of bundle size. Motion is not tiny. Three.js is large. Lazy-load anything that's not above-the-fold. + +### 6.F Z-Index Restraint +NEVER spam arbitrary `z-50` or `z-10`. Use z-index strictly for systemic layer contexts (sticky navbars, modals, overlays, grain). Document the z-index scale in a project constants file. + +--- + +## 7. DIAL DEFINITIONS (Technical Reference) + +### DESIGN_VARIANCE (Level 1-10) +* **1-3 (Predictable):** Symmetrical CSS Grid (12-col, equal fr-units), equal paddings, centered alignment. +* **4-7 (Offset):** `margin-top: -2rem` overlaps, varied image aspect ratios (4:3 next to 16:9), left-aligned headers over center-aligned data. +* **8-10 (Asymmetric):** Masonry layouts, CSS Grid with fractional units (`grid-template-columns: 2fr 1fr 1fr`), massive empty zones (`padding-left: 20vw`). +* **MOBILE OVERRIDE:** For levels 4-10, asymmetric layouts above `md:` MUST collapse to strict single-column (`w-full`, `px-4`, `py-8`) on viewports `< 768px`. + +### MOTION_INTENSITY (Level 1-10) +* **1-3 (Static):** No automatic animations. CSS `:hover` and `:active` states only. `prefers-reduced-motion` is the default mode anyway. +* **4-7 (Fluid CSS):** `transition: all 0.3s cubic-bezier(0.16, 1, 0.3, 1)`. `animation-delay` cascades for load-ins. Focus on `transform` and `opacity`. +* **8-10 (Advanced Choreography):** Complex scroll-triggered reveals, parallax, scroll-driven animation (CSS `animation-timeline` or GSAP ScrollTrigger). Use Motion hooks. **NEVER use `window.addEventListener('scroll')`** - it is a hard ban, not a "prefer-not." See Section 5.D for the allowed alternatives. + +### VISUAL_DENSITY (Level 1-10) +* **1-3 (Art Gallery):** Lots of white space. Huge section gaps (`py-32` to `py-48`). Expensive, clean. +* **4-7 (Daily App):** Standard web app spacing (`py-16` to `py-24`). +* **8-10 (Cockpit):** Tight paddings. No card boxes; 1px lines separate data. Mandatory: `font-mono` for all numbers. + +--- + +## 8. DARK MODE PROTOCOL + +Dual-mode by default. Never assume light-only unless the brief is print-emulating editorial. + +### 8.A Token Strategy (pick one, stick to it) +* **Tailwind `dark:` variant** (default for utility-first projects): every color utility paired with its dark variant (`bg-white dark:bg-zinc-950`, `text-gray-900 dark:text-gray-100`). +* **CSS variables** (for shadcn/ui, Radix Themes, or component libraries with theming): define semantic tokens (`--surface`, `--surface-elevated`, `--text-primary`, `--accent`) and swap values under `[data-theme="dark"]` or `@media (prefers-color-scheme: dark)`. + +### 8.B Do Not Prescribe Specific Colors Here +The brief and brand decide. This skill enforces only: +* **Contrast** - WCAG AA minimum for body text, AAA target for hero copy. +* **Hierarchy parity** - visual hierarchy that works in light must work in dark. If a CTA pops in light, it pops in dark. +* **Brand fidelity** - primary brand color stays recognisable. Don't desaturate the brand into a dark mode. +* **No pure `#000000` and no pure `#ffffff`** - use off-black (zinc-950, near-black warm gray) and off-white. Pure values kill depth. + +### 8.C Default Mode +Respect `prefers-color-scheme` unless the brand insists. Add a manual toggle if either mode would lose key brand expression. + +### 8.D Test in Both Modes Before Finishing +Open the page in both modes during development. Do not ship a page you've only seen in one mode. + +--- + +## 9. AI TELLS (Forbidden Patterns) + +Avoid these signatures unless the brief explicitly asks for them. + +### 9.A Visual & CSS +* **NO neon / outer glows** by default. Use inner borders or subtle tinted shadows. +* **NO pure black (`#000000`).** Off-black, zinc-950, or charcoal. +* **NO oversaturated accents.** Desaturate to blend with neutrals. +* **NO excessive gradient text** for large headers. +* **NO custom mouse cursors.** Outdated, accessibility-hostile, perf-hostile. + +### 9.B Typography +* **AVOID Inter as default.** See Section 4.1. Override path exists. +* **NO oversized H1s** that just scream. Control hierarchy with weight + color, not raw scale. +* **Serif constraints:** Serif for editorial / luxury / publication. Not for dashboards. + +### 9.C Layout & Spacing +* **Mathematically perfect** padding and margins. No floating elements with awkward gaps. +* **NO 3-column equal feature cards.** The generic "three identical cards horizontally" feature row is banned. Use 2-column zig-zag, asymmetric grid, scroll-pinned, or horizontal-scroll alternative. + +### 9.D Content & Data ("Jane Doe" Effect) +* **NO generic names.** "John Doe", "Sarah Chan", "Jack Su" → use creative, realistic, locale-appropriate names. +* **NO generic avatars.** No SVG "egg" or Lucide user icons → use believable photo placeholders or specific styling. +* **NO fake-perfect numbers.** Avoid `99.99%`, `50%`, `1234567`. Use organic, messy data (`47.2%`, `+1 (312) 847-1928`). +* **NO startup-slop brand names.** "Acme", "Nexus", "SmartFlow", "Cloudly" → invent contextual, premium names that sound real. +* **NO filler verbs.** "Elevate", "Seamless", "Unleash", "Next-Gen", "Revolutionize" → concrete verbs only. + +### 9.E External Resources & Components +* **NO hand-rolled SVG icons.** Use Phosphor / HugeIcons / Radix / Tabler. Lucide on explicit request only. +* **Hand-rolled decorative SVGs strongly discouraged** as default (see Section 4.8). +* **NO div-based fake screenshots.** Never build a fake product UI out of `
      ` rectangles to simulate a screenshot. Use real images, generated images, or skip the preview. +* **NO broken Unsplash links.** Use `https://picsum.photos/seed/{descriptive-string}/{w}/{h}`, or generated photo placeholders, or actual assets. +* **shadcn/ui customization:** Allowed, but NEVER in default state. Customize radii, colors, shadows, typography to the project aesthetic. +* **Production-Ready Cleanliness:** Code visually clean, memorable, meticulously refined. + +### 9.F Production-Test Tells (banned outright) + +These patterns came out of real LLM-generated landing-page tests. They are the signatures the model defaults to when it tries to "look designed." Treat them as hard bans unless the brief explicitly calls for one. + +**Hero & top-of-page** +* **NO version labels in the hero.** `V0.6`, `v2.0`, `BETA`, `INVITE-ONLY PREVIEW`, `EARLY ACCESS`, `ALPHA` - banned as default eyebrows. Only acceptable when the brief is explicitly about a product launch / preview status. +* **NO "Brand · No. 01"-style sub-eyebrows.** "Marrow · No. 01 · The 6-quart" type micro-meta lines. Skip them. + +**Section numbering & micro-labels** +* **NO section-number eyebrows.** `00 / INDEX`, `001 · Capabilities`, `002 · Featured commission`, `06 · how it works`, `05 · The honest table` - banned. Eyebrows should name the topic in plain language, not enumerate. +* **NO `01 / 4`-style pagination on images or bento tiles.** If the user can count, they don't need the label. +* **NO `Scroll · 001 Capabilities`-style scroll cues.** A simple arrow or "Scroll" is enough; no section-number prefix. +* **NO "Index of Work, 2018 - 2026"-style range labels** as eyebrows. Just say what the section is. + +**Separators & dots** +* **The middle-dot (`·`) is rationed.** Maximum 1 per line in metadata strips. Do NOT use it as the default separator for everything ("foo · bar · baz · qux · quux"). If you need a separator family, prefer line breaks, hairlines, or columns. +* **NO decorative colored status dots on every list/nav/badge.** A colored dot before "ONE Q4 SLOT OPEN" or before every nav link, or every task row - banned by default. Acceptable only when the dot conveys actual semantic state (a server status, an availability flag) and is used sparingly. + +**Em-dashes & typography flourishes** +* **NO em-dash (`—`) as a design element OR anywhere else.** See Section 9.G below for the complete, non-negotiable ban. The em-dash character is forbidden in headlines, eyebrows, pills, body copy, quotes, attribution, captions, button text, and alt text. Use the regular hyphen (`-`). +* **NO `
      `-broken-and-italicized headlines** as a default "design move." "for thirty\*years.*" type splits. Headlines should read naturally first, get clever only when the brief demands it. +* **NO vertical rotated text** ("INDEX OF WORK, 2018 - 2026" rotated 90°). Agency-portfolio cliché. Use it only when the brief is explicitly agency / Awwwards / experimental AND it serves a real composition purpose. +* **NO crosshair / hairline grid lines as decoration.** Vertical and horizontal lines drawn just to make the page "feel designed" - banned. Use them only when they organize real content. + +**Fake product previews** +* **NO div-based fake product UI in the hero** (fake task list, fake terminal, fake dashboard built from styled divs). It is the #1 LLM-design Tell. Use a real screenshot, a generated image, a real component preview, or none at all. +* **NO fake version footers** ("v0.6.2-rc.1", "last sync 4s ago · main") inside fake screenshots. Adds nothing, screams AI. + +**Marketing-copy Tells** +* **NO "Quietly in use at" / "Quietly trusted by"** social-proof headers. Use natural language: "Trusted by", "Used at", "Customers include", or skip the heading entirely if the logos speak. +* **NO "From the field" / "Field notes" / "Currently on the bench" / "On our desks" / "Loose plates" style poetic labels** on quote, blog, or sidebar sections. Reads as performative-craftsman. Use plain functional labels ("Testimonials", "Latest writing", "Now working on") or skip the label. +* **NO "We respect the French ones"-style** mock-humble industry-references in body copy. Cute and AI-y. +* **NO weather / locale strips** ("LIS 14:23 · 18°C") in headers/footers unless the brief is explicitly about a place / time-zone-distributed studio. +* **NO micro-meta-sentences under eyebrows.** Sentences like *"Each of these is a feature we ship today, not a roadmap promise. The list will stay short on purpose."* sitting under a section heading are clutter. Eyebrow + Headline + Body is enough. +* **NO generic step labels.** "Stage 1 / Stage 2 / Stage 3", "Step 1 / Step 2 / Step 3", "Phase 01 / Phase 02 / Phase 03", "Pass One / Pass Two / Pass Three". Banned. The actual step content is the label. If you must show progression, use the verb-noun directly ("Install", "Configure", "Ship") not "Stage 1: Install". + +**Pills, labels and version stamps** +* **NO pills/labels/tags overlaid on images.** No `` overlays on photos with tags like `Brand · 02`, `PLATE · BRAND`, `Field notes - journal`. Either let the image speak alone, or add a caption directly below (outside the image). +* **NO photo-credit captions as decoration.** Strings like `Field study no. 12 · Ines Caetano`, `Plate 03 · House archive`, `Frame XII · 35mm` under stock/picsum images are pretentious. Photo credit is allowed ONLY when there is a real photographer being credited for a real photo (with permission). Otherwise: skip the caption or use a one-line functional caption ("The 6-quart, in Sage."). +* **NO version footers on marketing pages.** Footer strings like `v1.4.2`, `Build 0048`, `last sync 4s ago · main` are CLI / devtool fixtures, not landing-page content. Banned on marketing/landing/portfolio pages. +* **NO "Reservation 412 of 800"-style live-stock counters** as decoration. Only if the brief is explicitly a limited-run waitlist with real data. + +**Decoration text strips** +* **NO decoration text strip at hero bottom.** Patterns like `BRAND. MOTION. SPATIAL.`, `TYPE / FORM / MOTION`, `DESIGN · BUILD · SHIP`, `ESTD. 2018 · LISBON · BRAND. MOTION. SPATIAL.` as a small mono-caps strip across the bottom of the hero are an agency-portfolio cliché. Banned by default. Only acceptable when the strip carries real, navigable links (sticky bottom nav) or real status info (cookie banner, build info on a docs site). +* **NO floating top-right sub-text in section headings.** Pattern: section has a giant left-aligned headline; in the top-right corner of the same section header there is a small explainer paragraph floating with no clear alignment to anything else. That floater is the Tell. Either put the sub-text directly under the headline, or build a clean 2-column header (left: headline, right: aligned body), but not a tiny corner paragraph. + +**Lists, dividers and scoring** +* **NO `border-t` + `border-b` on every row of a long list / spec table.** Pick one (bottom-border between rows OR top-border above the group) and use it sparsely. A 10-row spec table with hairlines under each row is the laziest layout - see Section 4.9 for alternative UI components. +* **NO scoring/progress bars with filled background tracks** as comparison visuals. If you need to show "X out of Y" comparisons, prefer a number + small icon, or a tiny inline bar WITHOUT a background track. Big filled `bg-zinc-200` tracks with a partial fill on top are dashboard-UI clutter on a landing page. + +**Locale, time, scroll cues** +* **Locale / city-name / time / weather strips are banned for 99% of briefs.** "Lisbon, working with founders" in the hero, "1200-690 Lisbon, Portugal" in the footer, "Lisbon 14:23 · 18°C" in the nav. These are agency-portfolio decoration tells. Allowed ONLY when: the brief explicitly describes a globally-distributed studio with timezone-relevant work, OR a travel-focused brand, OR a real-world physical venue. A single contact-address mention in the footer is fine; an atmospheric locale strip is not. +* **Scroll cues are banned.** `Scroll`, `↓ scroll`, `Scroll to explore`, `Scroll to walk through it`, animated mouse-wheel icons. If the user has not scrolled yet, they are looking at the hero. They know what scroll is. The bottom of the viewport does not need a label. +* **ZERO decorative status dots by default.** A coloured dot before nav items, before list rows, before badges, before status labels is a Tell. Only acceptable when conveying real semantic state (a live indicator on actual server status, a live availability flag) and limited to one per page section. + +### 9.G EM-DASH BAN (the single most-violated Tell) + +**Em-dash (`—`) is COMPLETELY banned.** It is the LLM's signature stylistic crutch and it is the #1 visual Tell in production tests. There is no "limited use" allowance, no "natural language frequency" allowance, no "in body copy is fine" allowance. None. + +* **Banned in headlines.** Use a period or a comma. +* **Banned in eyebrows / labels / pills / button text / image captions / nav items.** Replace with line breaks, columns, or hairlines. +* **Banned in body copy.** Restructure the sentence: two sentences with a period, OR a comma, OR parentheses, OR a colon. +* **Banned in quote attribution.** Use a normal hyphen with spaces (` - `) or a line break + smaller-weight name. +* **Banned in en-dash form too (`–`) when used as a separator.** Date ranges (`2018-2026`) use a hyphen. Number ranges (`€40-80k`) use a hyphen. + +The ONLY permitted dash characters on the page are: +* Regular hyphen `-` (for compound words, ranges, line dividers in markup) +* Minus sign in math (`-5°C`) + +If your output contains a single `—` or `–` anywhere visible to the user, the output fails the Pre-Flight Check and must be rewritten. + +This rule is non-negotiable. The agent has historically ignored em-dash limits when phrased as "use sparingly." The phrasing here is binary: zero em-dashes. + +--- + +## 10. REFERENCE VOCABULARY (Pattern Names the Agent Should Know) + +This is a vocabulary, not a library. The agent should KNOW these pattern names to communicate about them, design with them in mind, and reach for them when the design read calls for them. **Implementations and code sketches live in the Block Library (Section 12), which is populated iteratively.** + +### Hero Paradigms +* **Asymmetric Split Hero** - Text on one side, asset on the other, generous white space. +* **Editorial Manifesto Hero** - Large type, no asset, almost-poster. +* **Video / Media Mask Hero** - Type cut out as mask over video background. +* **Kinetic-Type Hero** - Animated typography as the primary visual. +* **Curtain-Reveal Hero** - Hero parts on scroll like a curtain. +* **Scroll-Pinned Hero** - Hero stays pinned while content scrolls behind. + +### Navigation & Menus +* **Mac OS Dock Magnification** - Edge nav, icons scale fluidly on hover. +* **Magnetic Button** - Pulls toward cursor. +* **Gooey Menu** - Sub-items detach like viscous liquid. +* **Dynamic Island** - Morphing pill for status / alerts. +* **Contextual Radial Menu** - Circular menu expanding at click point. +* **Floating Speed Dial** - FAB springing into curved secondary actions. +* **Mega Menu Reveal** - Full-screen dropdown, stagger-fade content. + +### Layout & Grids +* **Bento Grid** - Asymmetric tile grouping (Apple Control Center). +* **Masonry Layout** - Staggered grid, no fixed row height. +* **Chroma Grid** - Borders / tiles with subtle animating gradients. +* **Split-Screen Scroll** - Two halves sliding in opposite directions. +* **Sticky-Stack Sections** - Sections that pin and stack on scroll. + +### Cards & Containers +* **Parallax Tilt Card** - 3D tilt tracking mouse coordinates. +* **Spotlight Border Card** - Borders illuminate under cursor. +* **Glassmorphism Panel** - Frosted glass with inner refraction. +* **Holographic Foil Card** - Iridescent rainbow shift on hover. +* **Tinder Swipe Stack** - Physical card stack, swipe-away. +* **Morphing Modal** - Button expands into its own dialog. + +### Scroll Animations +* **Sticky Scroll Stack** - Cards stick and physically stack. +* **Horizontal Scroll Hijack** - Vertical scroll → horizontal pan. +* **Locomotive / Sequence Scroll** - Video / 3D sequence tied to scrollbar. +* **Zoom Parallax** - Central background image zooming on scroll. +* **Scroll Progress Path** - SVG line drawing along scroll. +* **Liquid Swipe Transition** - Page transition like viscous liquid. + +### Galleries & Media +* **Dome Gallery** - 3D panoramic gallery. +* **Coverflow Carousel** - 3D carousel with angled edges. +* **Drag-to-Pan Grid** - Boundless draggable canvas. +* **Accordion Image Slider** - Narrow strips expanding on hover. +* **Hover Image Trail** - Mouse leaves popping image trail. +* **Glitch Effect Image** - RGB-channel shift on hover. + +### Typography & Text +* **Kinetic Marquee** - Endless text bands reversing on scroll. +* **Text Mask Reveal** - Massive type as transparent window to video. +* **Text Scramble Effect** - Matrix-style decoding on load / hover. +* **Circular Text Path** - Text curving along spinning circle. +* **Gradient Stroke Animation** - Outlined text with running gradient. +* **Kinetic Typography Grid** - Letters dodging the cursor. + +### Micro-Interactions & Effects +* **Particle Explosion Button** - CTA shatters into particles on success. +* **Liquid Pull-to-Refresh** - Reload indicator like detaching droplets. +* **Skeleton Shimmer** - Shifting light reflection across placeholders. +* **Directional Hover-Aware Button** - Fill enters from cursor's exact side. +* **Ripple Click Effect** - Wave from click coordinates. +* **Animated SVG Line Drawing** - Vectors drawing themselves in real time. +* **Mesh Gradient Background** - Organic lava-lamp blobs. +* **Lens Blur Depth** - Background UI blurred to focus foreground action. + +### Animation Library Choice +* **Motion (`motion/react`)** - default for UI / Bento / state-change motion. +* **GSAP + ScrollTrigger** - for full-page scrolltelling and scroll hijacks. Isolate in dedicated leaf components with `useEffect` cleanup. +* **Three.js / WebGL** - for canvas backgrounds and 3D scenes. Same isolation rule. +* **NEVER mix GSAP / Three.js with Motion in the same component tree.** They fight over the same frames. + +--- + +## 11. REDESIGN PROTOCOL + +This skill handles **greenfield builds AND redesigns**. Misclassifying the mode is the single biggest source of bad redesign output. + +### 11.A Detect the Mode (first action) +* **Greenfield** - no existing site, or full overhaul approved. Dial baseline from Section 1. +* **Redesign - Preserve** - modernise without breaking the brand. Audit first, extract brand tokens, evolve gradually. +* **Redesign - Overhaul** - new visual language on top of existing content. Treat as greenfield for visuals; preserve content and IA. + +If ambiguous, ask **once**: *"Should this redesign preserve the existing brand, or are we starting visually from scratch?"* + +### 11.B Audit Before Touching +Document the current state before proposing changes: +* **Brand tokens** - primary / accent colors, type stack, logo treatment, radii. +* **Information architecture** - page tree, primary nav, key conversion paths. +* **Content blocks** - what exists, what's doing work, what's filler. +* **Patterns to preserve** - signature interactions, recognisable hero, copy voice. +* **Patterns to retire** - AI-slop tells, broken layouts, dead links, generic stock imagery, perf traps. +* **Dial reading of the existing site** - infer current `DESIGN_VARIANCE` / `MOTION_INTENSITY` / `VISUAL_DENSITY`. That's your starting point, not the baseline. +* **SEO baseline** - current ranking pages, meta titles, structured data, OG cards. **SEO migration is the #1 redesign risk.** + +### 11.C Preservation Rules +* **Do not change information architecture** unless asked. Keep page slugs, anchor IDs, primary nav labels stable for SEO and muscle memory. +* **Extract brand colors before applying Section 4.2.** A brand that is already purple stays purple - apply the LILA RULE's override. +* **Preserve copy voice** unless asked for a rewrite. Visual modernisation ≠ content rewrite. +* **Honor existing accessibility wins.** Do not regress focus states, alt text, keyboard nav, contrast. +* **Respect existing analytics events.** Do not rename buttons, form fields, section IDs that downstream tracking depends on. + +### 11.D Modernisation Levers (priority order) +Apply in order - stop when the brief is satisfied: +1. **Typography refresh** - biggest visual lift per unit of risk. +2. **Spacing & rhythm** - increase section padding, fix vertical rhythm. +3. **Color recalibration** - desaturate, unify neutrals, keep brand accent. +4. **Motion layer** - add `MOTION_INTENSITY`-appropriate micro-interactions to existing components. +5. **Hero & key-section recomposition** - restructure top-of-funnel using Section 10 vocabulary. +6. **Full block replacement** - only when the existing block is unsalvageable. + +### 11.E Decision Tree: Targeted Evolution vs Full Redesign +* IA, content, and SEO sound → **targeted evolution** (Levers 1-4). ~70% of value at ~40% of risk. +* Visual debt is structural (broken IA, no design system, broken mobile) → **full redesign** with strict content preservation. +* Brand itself is changing → **greenfield**. + +### 11.F What Never Changes Silently +Never modify without explicit user approval: +* URL structure / route slugs. +* Primary nav labels. +* Form field names or order (breaks analytics + autofill). +* Brand logo or wordmark. +* Existing legal / consent / cookie copy. + +--- + +## 12. THE BLOCK LIBRARY (Contract - Implementations Land Here Iteratively) + +The Reference Vocabulary (Section 10) names patterns. The Block Library implements them with real props, real motion specs, and real code sketches. + +**Status:** schema defined here. Blocks will be added iteratively. Do not freelance new blocks without following this schema. + +### 12.A File Location +``` +skills/taste-skill/blocks/ + hero/ + asymmetric-split.md + editorial-manifesto.md + kinetic-type.md + ... + feature/ + bento-grid.md + sticky-scroll-stack.md + zig-zag.md + ... + social-proof/ + pricing/ + cta/ + footer/ + navigation/ + portfolio/ + transition/ +``` + +### 12.B Required Frontmatter +```yaml +--- +name: asymmetric-split-hero +category: hero +dial_compatibility: + variance: [6, 10] + motion: [3, 10] + density: [2, 5] +when_to_use: "Landing pages with one strong asset and one strong message. Default hero for SaaS, agency, premium consumer." +not_for: "Editorial / manifesto launches where the message IS the design." +stack: ["react", "next", "tailwind", "motion"] +--- +``` + +### 12.C Required Body Sections +1. **Visual sketch** - short ASCII or description of the layout. +2. **Props API** - the component's interface. +3. **Code sketch** - minimal working implementation (Server Component default, Client island for motion). +4. **Mobile fallback** - explicit collapse rules for `< 768px`. +5. **Motion variants** - one variant per `MOTION_INTENSITY` band (1-3, 4-7, 8-10). Reduced-motion fallback explicit. +6. **Dark-mode notes** - token strategy specific to this block. +7. **Anti-patterns** - common ways this block goes wrong. +8. **References** - links to real examples in production. + +### 12.D Block-Library Discipline +* One block per file. No multi-block files. +* Every block must work standalone (drop it into a page, it renders). +* Every block must pass the Pre-Flight Check (Section 14). +* Blocks that depend on a design system from Section 2.A live under `blocks//--.md` (e.g. `feature/bento-grid--material.md`). + +--- + +## 13. OUT OF SCOPE + +This skill is NOT for: +* Dashboards / dense product UI / admin panels (use Fluent, Carbon, Atlassian, or Polaris from Section 2.A). +* Data tables (use TanStack Table or AG Grid). +* Multi-step forms / wizards (use Form-specific patterns; this skill won't make them better). +* Code editors (use Monaco / CodeMirror with their official skinning). +* Native mobile (use Apple HIG / Material directly). +* Realtime collab UIs (presence, cursors, OT-aware - different problem class). + +If the brief is one of the above, **say so explicitly**, point to the right tool, and only apply this skill's marketing-page / about-page / landing-page parts to the surfaces where they apply. + +--- + +## 14. FINAL PRE-FLIGHT CHECK + +Run this matrix before outputting code. This is the last filter. + +**THIS IS NOT OPTIONAL. Run every box. If any box fails, the output is not done.** + +- [ ] **Brief inference** declared (Section 0.B one-liner)? +- [ ] **Dial values** explicit and reasoned from the brief, not silently using baseline? +- [ ] **Design system** chosen from Section 2 if applicable, or aesthetic labeled honestly? +- [ ] **Redesign mode** detected and audit performed (if applicable, Section 11)? +- [ ] **ZERO em-dashes (`—`) anywhere on the page.** Headlines, eyebrows, pills, body, quotes, attribution, captions, buttons, alt text. Zero. (Section 9.G - non-negotiable.) +- [ ] **Page Theme Lock**: ONE theme (light, dark, or auto) for the whole page. No section flips to inverted mode mid-page (Section 4.11)? +- [ ] **Color Consistency Lock**: one accent color used identically across all sections (Section 4.2)? +- [ ] **Shape Consistency Lock**: one corner-radius system applied consistently (Section 4.4)? +- [ ] **Button Contrast Check**: every CTA text is readable against its background (no white-on-white, WCAG AA 4.5:1)? +- [ ] **CTA Button Wrap**: no CTA label wraps to 2+ lines at desktop? +- [ ] **Form Contrast Check**: form inputs, placeholders, focus rings, labels all pass WCAG AA against the section background? +- [ ] **Serif discipline**: if a serif is used, it is NOT Fraunces or Instrument_Serif (or it is, with explicit brand justification)? Different serif from your previous project? +- [ ] **Premium-consumer palette check**: if the brief is premium-consumer (cookware / wellness / artisan / luxury), the palette is NOT the AI-default beige+brass+oxblood+espresso family? Different family from your previous premium-consumer project? +- [ ] **Italic descender clearance**: every italic word with `y g j p q` has `leading-[1.1]` min + `pb-1` reserve? +- [ ] **Hero fits the viewport**: headline ≤ 2 lines, subtext ≤ 20 words AND ≤ 4 lines, CTA visible without scroll, font scale planned around image? +- [ ] **Hero top padding**: max `pt-24` at desktop, hero content does not float halfway down the viewport? +- [ ] **Hero stack discipline**: max 4 text elements in hero (eyebrow OR brand strip, headline, subtext, CTAs)? No tiny tagline below CTAs, no trust micro-strip in hero? +- [ ] **EYEBROW COUNT (mechanical)**: count instances of `uppercase tracking` micro-labels above section headlines across all components. Count ≤ ceil(sectionCount / 3)? Hero counts as 1. +- [ ] **Split-Header Ban**: no "left big headline + right small explainer paragraph" pattern as a section header (vertical stack instead)? +- [ ] **Zigzag Alternation Cap**: no 3+ consecutive sections with the same image+text-split layout? +- [ ] **No Duplicate CTA Intent**: no two CTAs with the same intent ("Get in touch" + "Let's talk" both on page = Fail)? +- [ ] **Logo wall = logo only**: no industry / category labels printed below logos? +- [ ] **Bento Background Diversity**: at least 2-3 bento cells have real visual variation (image, gradient, pattern), not all white-on-white text cards? +- [ ] **"Used by / Trusted by" logo wall** lives UNDER the hero, not inside it, uses REAL SVG logos (Simple Icons / devicon) or generated SVG marks, NOT plain text wordmarks? +- [ ] **Copy Self-Audit**: every visible string re-read, no grammatically-broken or AI-hallucinated phrases ("free on its past" type) shipped? +- [ ] **Motion motivated**: every animation can be justified in one sentence (hierarchy / storytelling / feedback / state transition), no GSAP-for-show? +- [ ] **Marquee max-one-per-page**: no two horizontal marquees on the same page? +- [ ] **Navigation on ONE line** at desktop, height ≤ 80px? +- [ ] **Section-Layout-Repetition** check: no two sections share the same layout family (at least 4 different families across 8 sections)? +- [ ] **Bento has rhythm AND exact cell count** (N items → N cells, no empty cells in middle or at end)? +- [ ] **Long lists use the right UI component** (not default `
        ` with `divide-y` for > 5 items - see Section 4.9 alternatives)? +- [ ] **Real images used** (gen-tool first, then Picsum-seed, then explicit placeholder slots) - NO div-based fake screenshots, NO hand-rolled decorative SVGs, NO pure-text minimalism? +- [ ] **No pills/labels overlaid on images** (no `Plate · Brand`, no `Field notes - journal`)? +- [ ] **No photo-credit captions as decoration** (`Field study no. 12 · Ines Caetano`)? +- [ ] **No version footers** (`v1.4.2`, `Build 0048`) on marketing pages? +- [ ] **No micro-meta-sentences** under eyebrows ("Each of these is a feature we ship today...")? +- [ ] **No decoration text strip at hero bottom** (`BRAND. MOTION. SPATIAL.`)? +- [ ] **No floating top-right sub-text** in section headings? +- [ ] **No scoring/progress bars with filled background tracks** as comparison visuals? +- [ ] **No locale / city-name / time / weather strips** unless brief is genuinely globally-distributed or place-focused? +- [ ] **No scroll cues** (`Scroll`, `↓ scroll`, `Scroll to explore`)? +- [ ] **No version labels in hero** (V0.6, BETA, INVITE-ONLY) unless the brief is a launch? +- [ ] **No section-numbering eyebrows** (`00 / INDEX`, `001 · Capabilities`, `06 · how it works`)? +- [ ] **No decorative dots** (zero by default, only for real semantic state)? +- [ ] **No `border-t` + `border-b` on every row** of long lists / spec tables? +- [ ] **Content density** sane: no 20-row data tables, no fake-precise specs without justification, ≤ 25-word sub-paragraphs by default? +- [ ] **Quotes ≤ 3 lines** of body, attribution clean (no em-dash)? +- [ ] **Motion claimed = motion shown**: if `MOTION_INTENSITY > 4`, page actually animates, not just claimed? +- [ ] **GSAP sticky-stack / horizontal-pan** implemented per Section 5.A / 5.B canonical skeleton (`start: "top top"`, `pin: true`, correct scrub)? +- [ ] **No `window.addEventListener('scroll')`** - using Motion `useScroll()` / ScrollTrigger / IntersectionObserver / CSS scroll-driven animations only? +- [ ] **Reduced motion** wrapped for everything `MOTION_INTENSITY > 3`? +- [ ] **Dark mode** tokens defined and tested in both modes? +- [ ] **Mobile collapse** explicit (`w-full`, `px-4`, `max-w-7xl mx-auto`) for high-variance layouts? +- [ ] **Viewport stability**: `min-h-[100dvh]`, never `h-screen`? +- [ ] **`useEffect` animations** have strict cleanup functions? +- [ ] **Empty / loading / error** states provided? +- [ ] **Cards omitted** in favor of spacing where possible? +- [ ] **Icons** from an allowed library only (Phosphor / HugeIcons / Radix / Tabler), no hand-rolled SVG paths? +- [ ] **Motion** isolated in client-leaf components with `'use client'` at the top, memoized? +- [ ] **No AI Tells** from Section 9 (Inter as default, AI-purple, three-equal cards, Jane Doe, Acme, "Quietly in use at")? +- [ ] **Core Web Vitals** plausibly hit (LCP < 2.5s, INP < 200ms, CLS < 0.1)? +- [ ] **One design system** per project (no Material + shadcn mixed)? + +If a single checkbox cannot be honestly ticked, the page is not done. Fix it before delivering. + +--- + +# APPENDICES - Real Source-Backed Reference Material + +The sections below are vendored reference content. They give the agent real install commands, real canonical doc links, and real working starter snippets for each design system named in Section 2. Use them to ground decisions in production reality, not training-data fiction. + +## Appendix A - Install Commands per Design System + +```bash +# Material Web (Material 3) +npm install @material/web + +# Fluent UI React (v9) +npm install @fluentui/react-components + +# Fluent UI Web Components (framework-free) +npm install @fluentui/web-components @fluentui/tokens + +# IBM Carbon +npm install @carbon/react @carbon/styles + +# Radix Themes +npm install @radix-ui/themes + +# shadcn/ui (open code, owned components) +npx shadcn@latest init +npx shadcn@latest add button card badge separator input + +# Primer CSS (GitHub product/devtool UI) +npm install --save @primer/css + +# Primer Brand (GitHub marketing UI) +npm install @primer/react-brand + +# GOV.UK Frontend +npm install govuk-frontend + +# USWDS (US Web Design System) +npm install uswds + +# Atlassian Design System (Atlaskit) +yarn add @atlaskit/css-reset @atlaskit/tokens @atlaskit/button @atlaskit/badge @atlaskit/section-message @atlaskit/card + +# Bootstrap 5.3 +npm install bootstrap + +# Shopify Polaris Web Components (Shopify apps only) +# Add this to your app HTML head: +# +# +``` + +## Appendix B - Canonical Sources (read these before reinventing) + +### Material Web +- https://github.com/material-components/material-web +- https://material-web.dev/theming/material-theming/ +- https://m3.material.io/develop/web + +### Fluent UI +- https://fluent2.microsoft.design/get-started/develop +- https://fluent2.microsoft.design/components/web/react/ +- https://github.com/microsoft/fluentui +- https://learn.microsoft.com/en-us/fluent-ui/web-components/ + +### Carbon +- https://carbondesignsystem.com/ +- https://github.com/carbon-design-system/carbon +- https://carbondesignsystem.com/developing/react-tutorial/overview/ +- https://carbondesignsystem.com/developing/web-components-tutorial/overview/ + +### Shopify Polaris +- https://shopify.dev/docs/api/app-home/web-components +- https://github.com/Shopify/polaris-react +- https://polaris-react.shopify.com/components + +### Atlassian +- https://atlassian.design/get-started/develop +- https://atlassian.design/components/button/examples +- https://atlaskit.atlassian.com/packages/design-system/button/example/disabled +- https://atlassian.design/tokens/design-tokens + +### Primer +- https://primer.style/ +- https://github.com/primer/css +- https://github.com/primer/brand + +### GOV.UK +- https://design-system.service.gov.uk/components/button/ +- https://design-system.service.gov.uk/styles/layout/ +- https://github.com/alphagov/govuk-frontend + +### USWDS +- https://designsystem.digital.gov/documentation/developers/ +- https://designsystem.digital.gov/components/button/ +- https://designsystem.digital.gov/components/card/ +- https://github.com/uswds/uswds + +### Bootstrap +- https://getbootstrap.com/docs/5.3/layout/grid/ +- https://getbootstrap.com/docs/5.3/components/card/ + +### Tailwind +- https://tailwindcss.com/docs/dark-mode +- https://tailwindcss.com/blog/tailwindcss-v4 + +### Radix +- https://www.radix-ui.com/themes/docs/components/theme +- https://www.radix-ui.com/themes/docs/components/card +- https://github.com/radix-ui/themes + +### shadcn/ui +- https://ui.shadcn.com/docs +- https://ui.shadcn.com/docs/components/card +- https://github.com/shadcn-ui/ui + +### Native CSS / W3C standards +- https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/backdrop-filter +- https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/prefers-color-scheme +- https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/prefers-reduced-motion +- https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Grid_layout +- https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Scroll-driven_animations +- https://drafts.csswg.org/scroll-animations-1/ + +### Apple Liquid Glass (Apple platforms only) +- https://developer.apple.com/design/human-interface-guidelines/materials +- https://developer.apple.com/documentation/TechnologyOverviews/liquid-glass +- https://developer.apple.com/documentation/TechnologyOverviews/adopting-liquid-glass +- https://developer.apple.com/documentation/SwiftUI/Material + +--- + +## Appendix C - Apple Liquid Glass: Honest Web Approximation + +Do **not** treat random CSS snippets as official Apple Liquid Glass. + +### What is official +Apple documents Liquid Glass inside Apple's Human Interface Guidelines and Developer Documentation for **Apple platforms**. It is a dynamic material used across Apple platform UI. Apple's native implementation belongs to Apple platform APIs and system components, **not a public web CSS package**. + +Relevant official docs: +- Apple Human Interface Guidelines → Materials +- Apple Developer Documentation → Liquid Glass +- Apple Developer Documentation → Adopting Liquid Glass +- SwiftUI → Material + +### What is NOT official +There is no `liquid-glass.css` from Apple for normal websites. + +A web approximation can use: +- `backdrop-filter` +- transparent backgrounds +- layered borders +- highlight overlays +- gradients +- motion +- strong contrast fallbacks + +But that is **web glassmorphism / frosted-glass approximation**, not official Apple Liquid Glass. Label it as such in comments. + +### Safer web approximation skeleton + +```css +.liquid-glass-web-approx { + position: relative; + isolation: isolate; + overflow: hidden; + border-radius: 999px; + border: 1px solid rgb(255 255 255 / .32); + background: + linear-gradient(135deg, rgb(255 255 255 / .30), rgb(255 255 255 / .08)), + rgb(255 255 255 / .12); + backdrop-filter: blur(24px) saturate(180%) contrast(1.05); + -webkit-backdrop-filter: blur(24px) saturate(180%) contrast(1.05); + box-shadow: + inset 0 1px 0 rgb(255 255 255 / .48), + inset 0 -1px 0 rgb(255 255 255 / .12), + 0 18px 60px rgb(0 0 0 / .18); +} + +.liquid-glass-web-approx::before { + content: ""; + position: absolute; + inset: 0; + z-index: -1; + border-radius: inherit; + background: + radial-gradient(circle at 20% 0%, rgb(255 255 255 / .55), transparent 34%), + linear-gradient(90deg, rgb(255 255 255 / .18), transparent 42%, rgb(255 255 255 / .14)); + pointer-events: none; +} + +.liquid-glass-web-approx::after { + content: ""; + position: absolute; + inset: 1px; + border-radius: inherit; + border: 1px solid rgb(255 255 255 / .14); + pointer-events: none; +} + +@media (prefers-color-scheme: dark) { + .liquid-glass-web-approx { + border-color: rgb(255 255 255 / .18); + background: + linear-gradient(135deg, rgb(255 255 255 / .16), rgb(255 255 255 / .04)), + rgb(15 23 42 / .42); + box-shadow: + inset 0 1px 0 rgb(255 255 255 / .22), + 0 18px 60px rgb(0 0 0 / .42); + } +} + +@media (prefers-reduced-transparency: reduce) { + .liquid-glass-web-approx { + background: rgb(255 255 255 / .96); + backdrop-filter: none; + -webkit-backdrop-filter: none; + } +} +``` + +**Important:** `prefers-reduced-transparency` has uneven browser support; test it. Always provide enough contrast even without blur. + +--- + +**End of appendices.** Install commands above are reality anchors. The Apple Liquid Glass skeleton is a labeled approximation, not an Apple-issued package. For canonical docs per design system, consult the system's official docs (links in Section 2 plus Appendix B). diff --git a/.agents/skills/imagegen-frontend-web/SKILL.md b/.agents/skills/imagegen-frontend-web/SKILL.md new file mode 100644 index 00000000..26b293b8 --- /dev/null +++ b/.agents/skills/imagegen-frontend-web/SKILL.md @@ -0,0 +1,987 @@ +--- +name: imagegen-frontend-web +description: Elite frontend image-direction skill for generating premium, conversion-aware website design references. CRITICAL OUTPUT RULE — generate ONE separate horizontal image FOR EVERY section. A landing page with 8 sections produces 8 images. Never compress multiple sections into one image. Enforces composition variety (not always left-text / right-image), background-image freedom, varied CTAs, varied hero scales (giant / mid / mini minimalist), narrative concept spine, second-read moments, and a single consistent palette across all images. Optimized for landing pages, marketing sites, and product comps that developers or coding models can accurately recreate. +--- + +# HARD OUTPUT RULE — READ FIRST + +**Generate one separate horizontal image PER section. Always. No exceptions.** + +- 1 section requested -> 1 image +- 4 sections requested -> 4 images +- 8 sections requested -> 8 images +- 12 sections requested -> 12 images +- "landing page" with no count -> default to 6 sections -> 6 images +- "full website template" -> default to 8 sections -> 8 images + +Each image is one section, generated as its own image call. Never combine multiple sections into one frame. Never return a single tall image that contains the whole page. + +If you can only render one image at a time, output them sequentially in the same response, one after the other, until every section has its own image. Announce each one ("Section 1 of 8: Hero", "Section 2 of 8: Trust bar", etc.). + +This rule overrides any model default that wants to collapse output into a single image. + +--- + +# HERO COMPOSITION BIAS — READ FIRST + +The default **left-text / right-image hero is the most overused AI pattern**. It is allowed, but it should not be your first instinct. + +Before reaching for it, consider these alternatives and pick whichever fits the brand best: +- centered over background image +- bottom-left over image +- bottom-right over image +- top-left lead +- stacked center +- image-as-canvas +- off-grid editorial +- mini minimalist +- right-text / left-image (inverted classic) + +Use left-text / right-image only when it is genuinely the strongest choice — not by default. + +--- + +# CORE DIRECTIVE: AWWWARDS-LEVEL IMAGE ART DIRECTION +You are an elite frontend image art director. + +Your job is not to generate generic AI art. +Your job is to generate highly creative, premium, frontend design reference images that feel like real high-end website concepts. + +Standard image generation tends to collapse into repetitive defaults: +- centered dark hero +- purple/blue AI glow +- floating meaningless blobs +- generic dashboard card spam +- weak typography hierarchy +- cloned sections +- "luxury" that is just beige serif text +- "creative" that is actually messy and unreadable +- text-heavy layouts with not enough imagery +- overly dense sections with no breathing room + +Your goal is to aggressively break these defaults. + +The output must feel: +- art-directed +- premium +- visually memorable +- structured +- readable +- implementation-friendly +- clearly usable as a frontend reference + +Do not generate random mood art unless explicitly asked. +Default to website design comps. + +--- + +## 1. ACTIVE BASELINE CONFIGURATION + +- DESIGN_VARIANCE: 8 + `(1 = rigid / symmetrical, 10 = artsy / asymmetric)` +- VISUAL_DENSITY: 4 + `(1 = airy / gallery-like, 10 = packed / intense)` +- ART_DIRECTION: 8 + `(1 = safe commercial, 10 = bold creative statement)` +- IMPLEMENTATION_CLARITY: 9 + `(1 = loose moodboard, 10 = very codeable UI reference)` +- IMAGE_USAGE_PRIORITY: 9 + `(1 = mostly typographic, 10 = strongly image-led)` +- SPACING_GENEROSITY: 8 + `(1 = compact / tight, 10 = very spacious / breathable)` +- LAYOUT_VARIATION: 8 + `(1 = same anchor repeats, 10 = bold composition variety across sections)` +- CONVERSION_DISCIPLINE: 8 + `(1 = pure art moodboard, 10 = clear funnel + premium design balance)` + +AI Instruction: +Use these as global defaults unless the user clearly asks for something else. +Do not ask the user to edit this file. +Adapt these values dynamically from the prompt. + +Interpretation: +- **Adaptation priority**: the user's brief always overrides defaults. Read the prompt carefully, then adjust dials, hero scale, background mode, gradient use, and composition variety to match — never force a recipe that contradicts the brief. +- If the user says "clean", reduce density and increase clarity. +- If the user says "crazy creative", increase variance and art direction. +- If the user says "premium SaaS", keep clarity high and art direction controlled. +- If the user says "editorial", allow stronger type and more asymmetry. +- Bias toward stronger visual concepts, not safe layouts — but never against the brief. +- Use imagery as a core design material — including as **full-bleed backgrounds**, not only as inline assets, **when the brief allows it**. +- Vary composition: do not default to "text left, image right". Move text to bottom-left, center, top-right, etc. across sections. +- Keep sections breathable. Do not over-pack the page. +- Prefer slightly more whitespace between sections than default. +- Stay conversion-aware: every section has a job (hook / proof / educate / convert). + +### Brief-to-direction mapping +Read the brief. Then bias the picks like this: + +If the user says **"minimalist" / "clean" / "typography-only" / "swiss" / "ultra simple"**: +- Hero Scale: Mini Minimalist +- Background Mode: solid surfaces, subtle texture, optional ONE color-blocked diptych +- Gradients: skip or use only the softest tonal gradient +- Composition: stacked center, generous negative space +- Skip the "must include full-bleed" rule + +If the user says **"editorial" / "magazine" / "art-directed" / "fashion"**: +- Hero Scale: Mid Editorial or Giant Statement +- Background Mode: editorial side-image, duotone treated image, atmospheric photo grade +- Gradients: subtle tonal grades only +- Composition: off-grid editorial offset, asymmetric pulls +- Strong typography contrast + +If the user says **"cinematic" / "atmospheric" / "premium" / "luxury" / "bold"**: +- Hero Scale: Giant Statement +- Background Mode: full-bleed image with tonal overlay, soft radial vignette + product, micro-noise gradient +- Gradients: cinematic palette-matched welcomed +- Composition: bottom-left over background image, centered low, image-as-canvas + +If the user says **"SaaS" / "product" / "dashboard" / "fintech" / "infra"**: +- Hero Scale: Mid Editorial +- Background Mode: solid + inline asset, flat block + detail crop, occasional editorial side-image +- Gradients: very subtle, palette-matched only +- Composition: clear product framing, trust-driven anchors +- Slightly higher implementation clarity + +If the user says **"agency" / "creative studio" / "portfolio"**: +- Hero Scale: Giant Statement OR Mini Minimalist (decisive) +- Background Mode: vary boldly (full-bleed image, color-blocked diptych, duotone) +- Gradients: editorial color washes acceptable +- Composition: off-grid, poster-like + +If the user says **"e-commerce" / "shop" / "store" / "product page"**: +- Hero Scale: Mid Editorial with strong product focus +- Background Mode: full-bleed product photo, soft radial vignette + crop, flat block + detail +- Gradients: subtle, never competing with product +- Composition: product-led; CTAs unmistakable + +If the brief is silent on style: +- Use defaults from §1 + §2 with confident background variety +- Pick one Hero Scale decisively, do not split the difference + +Never force backgrounds, gradients, or full-bleed treatments where the brief asks for restraint. Never strip them out where the brief asks for atmosphere. + +--- + +## 2. THE COMBINATORIAL VARIATION ENGINE +To avoid repetitive AI-looking output, internally choose one option from each category based on the prompt and commit to it consistently. + +Do not mash everything together into chaos. +Pick a strong combination and execute it clearly. + +### Theme Paradigm +Choose 1: +1. Pristine Light Mode + Off-white / cream / paper tones, sharp dark text, editorial confidence. +2. Deep Dark Mode + Charcoal / graphite / zinc, elegant glow only when justified. +3. Bold Studio Solid + Strong controlled color fields like oxblood, royal blue, forest, vermilion, or emerald with crisp contrasting UI. +4. Quiet Premium Neutral + Bone, sand, taupe, stone, smoke, muted contrast, restrained luxury. + +### Background Character +Choose 1: +1. Subtle technical grid / dotted field +2. Pure solid field with soft ambient gradient depth +3. Full-bleed cinematic imagery with proper contrast control +4. Quiet textured paper / material / tactile surface feel + +### Typography Character +Choose 1: +1. Satoshi-like clean grotesk +2. Neue-Montreal-like refined grotesk +3. Cabinet / Clash-like expressive display +4. Monument-like compressed statement typography +5. Elegant editorial serif + sans pairing +6. Swiss rational sans with very strong hierarchy + +Never drift into boring default web typography energy. + +### Hero Architecture +Choose 1: +1. Cinematic Centered Minimalist +2. Asymmetric Split Hero +3. Floating Polaroid Scatter +4. Inline Typography Behemoth +5. Editorial Offset Composition +6. Massive Image-First Hero with restrained text + +### Section System +Choose 1 dominant structure: +1. Strict modular bento rhythm +2. Alternating editorial blocks +3. Poster-like stacked storytelling +4. Gallery-led visual cadence +5. Swiss grid discipline +6. Asymmetric premium marketing flow + +### Signature Component Set +Choose exactly 4 unique components: +- Diagonal Staggered Square Masonry +- 3D Cascading Card Deck +- Hover-Accordion Slice Layout +- Pristine Gapless Bento Grid +- Infinite Brand Marquee Strip +- Turning Polaroid Arc +- Vertical Rhythm Lines +- Off-Grid Editorial Layout +- Product UI Panel Stack +- Split Testimonial Quote Wall +- Oversized Metrics Strip +- Layered Image Crop Frames + +### Motion-Implied Language +Choose exactly 2: +- scrubbing text reveal energy +- pinned narrative section energy +- staggered float-up energy +- parallax image drift energy +- smooth accordion expansion energy +- cinematic fade-through energy + +### Composition Anchor (per-section) +The **left-text / right-image** layout is allowed, but it is the most overused AI pattern — do not use it as the default. Reach for it only when it is the genuinely best fit. + +Each section picks 1 anchor; across the site at least 3 different anchors must appear; vary the hero so the page does not open on the AI default. +- Centered statement +- Top-left lead, support bottom-right +- Bottom-left text over background image +- Bottom-right CTA cluster +- Left-third caption + right-two-thirds visual (classic — use sparingly, never twice in a row) +- Right-third caption + left-two-thirds visual (inverted classic) +- Centered low (text in lower 40% over hero image) +- Off-grid editorial offset (asymmetric pull) +- Stacked center (label / headline / sub / CTA all centered, ultra minimalist) +- Image-as-canvas with text overlaid in a clean safe area + +### Background Mode (per-section) +Pick 1 per section; vary across the page so it is never all the same mode. Be **confident** with backgrounds — they are a primary tool, not a risk. +- Solid surface with inline asset +- Subtle texture / paper / grid as background +- Full-bleed image background with tonal overlay (text remains highly readable) +- Editorial side-image (50/50, 60/40, 40/60 — invertible) +- Image as the entire visual + text overlaid in a clean safe area +- Flat color block + small product / detail crop as accent +- Cinematic tonal gradient (palette-matched, low chroma, professional) +- Atmospheric photo with strong color grade (single-tone graded for brand mood) +- Duotone treated image (two-color photo treatment, palette-locked) +- Soft radial vignette + product crop (luxury / editorial feel) +- Micro-noise gradient over solid (premium tactile depth, not flashy) +- Color-blocked diptych (two flat fields meeting, modernist) + +### CTA Variation +Pick the CTA style that fits each section, not a default pill every time: +- Classic primary pill +- Outline / ghost +- Underlined inline link with arrow +- Banner-style full-width CTA +- Oversized headline + tiny CTA hint +- CTA as caption under a strong visual + +Across the site, vary CTA style at least once. The page's primary action stays unmistakable. + +### Hero Scale (per-page) +Pick 1 — must match brand mood: +- Giant Statement Hero (massive type, large image, dominant first viewport) +- Mid Editorial Hero (balanced type/image, cinematic but not screen-filling) +- Mini Minimalist Hero (tiny logo + short statement + thin CTA, almost no image, lots of negative space) + +Mini does not mean weak — it means confident restraint. + +### Narrative / Concept Spine +Pick 1 and let it thread through visuals and short copy across the page. +- Artifact / collectible — proof, specimen, treasured object framing +- Journey / pilgrimage — directional flow, waypoint sections, roadmap feeling +- Tool / precision instrument — machined detail, calibrated UI, tactile controls +- Living system / garden — organic growth metaphor, branching layout, nurtured tone +- Stage / spotlight — theatrical contrast, performer + audience framing +- Archive / dossier — indexed rows, captions, understated authority + +### Second-Read Moment +Pick exactly 1 unobvious but legible motif and place it deliberately, once across the page: +- asymmetric bleed that still respects hierarchy +- one oversized punctuation or numeral serving structure +- a single unexpected material switch (paper vs gloss vs metal accent) +- a narrow vertical side-rail editorial note style +- a macro crop that carries brand color naturally +Avoid gimmick-for-gimmick: the moment must aid scan order or brand recall. + +Important: +These are not coding instructions. +They are visual-direction cues the generated design should imply. + +--- + +## 3. FRONTEND REFERENCE RULE +Every generated image must clearly communicate: +- layout +- section hierarchy +- spacing +- typography scale +- visual rhythm +- CTA priority +- component styling +- image treatment +- overall design system + +A developer or coding model should be able to look at the image and understand how to build it. + +Do not produce vague abstract artwork when the request is for frontend. + +--- + +## 4. HERO MINIMALISM RULES +The hero must feel cinematic, clear, and intentional. + +### Hero Composition Bias +The **left-text / right-image hero is the most overused AI hero pattern**. It is allowed, but it should not be your default starting point. + +Prefer one of these instead, unless left-text / right-image is genuinely the strongest fit: +- Centered statement over full-bleed image (text in lower 40%) +- Bottom-left text over background image +- Bottom-right text over background image +- Top-left lead, support bottom-right +- Stacked center (label / headline / sub / CTA all centered) +- Image-as-canvas with text overlaid in a clean safe area +- Right-text / left-image (inverted classic) +- Off-grid editorial offset +- Mini Minimalist Hero (tiny logo + short statement + thin CTA, mostly negative space) + +### Pre-output check +Before rendering the hero image, ask yourself: "Am I drafting the default text-left / image-right layout out of habit?" If yes, prefer a different anchor from the list above unless the brief or brand truly requires the classic. + +### Absolute Hero Rules +- the hero must feel like a strong opening scene +- keep the hero composition clean +- do not overcrowd the first viewport +- the main headline must feel short and powerful +- headline should usually read like 5-10 strong words, not a paragraph +- keep supporting text concise +- prioritize negative space and contrast +- avoid stuffing the hero with pills, fake stats, badges, tiny logos, and nonsense detail + +### Headline Rule +The H1 should visually read like a premium statement. +Do not let it feel long, weak, or overly wrapped. + +### Typography Execution +Prefer: +- medium / normal / light elegance +- tight tracking +- controlled line count +- strong scale contrast + +Avoid: +- random extra-bold shouting everywhere +- gradient text as a lazy premium effect +- 6-line startup headings +- text treatment that looks generated + +### Graphic Restraint +Do not default to: +- giant meaningless outline numbers +- cheap SVG-looking filler graphics +- generic AI blobs +- random orb clutter + +Use: +- typography +- image crops +- real layout tension +- premium materials +- strong framing +instead. + +--- + +## 5. IMAGE COUNT & PAGE SLICING + +### THIS IS THE PRIMARY OUTPUT RULE +Generate **one separate horizontal image PER section**. Always. + +- never combine multiple sections in a single image +- never return a single tall slice that contains the whole page +- never return one "best" image and skip the rest +- never replace several sections with one collage + +If the request is ambiguous about section count, **default high**: +- "hero" -> 1 image +- "landing page" / "site template" -> default to 6 sections -> 6 images +- "full website" -> default to 8 sections -> 8 images +- "marketing site" -> default to 8 sections -> 8 images +- "product page" -> default to 6 sections -> 6 images +- "portfolio" -> default to 6 sections -> 6 images + +If the model can only render one image per call, generate them **sequentially in the same response**, one after the other, labeled "Section X of N: " until the full set is delivered. + +### Format +- Always horizontal (16:9, 16:10, or 21:9 depending on density) +- Each image renders one focused section in high fidelity +- Hero usually 16:9 or 21:9; narrower content sections may be 16:10 + +### Counting rule +- 1 section -> 1 horizontal image +- 4 sections -> 4 horizontal images +- 8 sections -> 8 horizontal images +- 12 sections -> 12 horizontal images + +Do not collapse multiple sections into one tall slice. Section size and density may still vary, but the canvas stays horizontal and **one section per frame**. + +### Section size variety +Across the site, mix section ambition deliberately: +- some sections are large, content-rich, art-directed +- some sections are mini, ultra minimalist, mostly negative space +- some sections are medium editorial blocks + +This rhythm creates a premium scrollscape, not uniform slabs. + +### Continuity Rule +Across all per-section images, enforce one brand world: +- same palette and accent logic +- same typography family and scale +- same CTA family (style variations are fine, identity is not) +- same border radius language +- same image treatment (color grade, materials, framing) +- same tonal voice in any short copy + +A viewer scrolling through all frames must read them as one site. + +--- + +## 6. CREATIVITY ESCALATION RULE +The design must show real creative ambition. + +Do not settle for the first obvious layout solution. +Push the work beyond generic SaaS patterns. + +Actively increase at least 3 of these: +- stronger composition +- more distinctive typography +- more confident scale contrast +- more memorable hero concept +- more interesting image treatment +- more expressive section rhythm +- more original framing / cropping +- more art-directed visual tension +- more surprising but clear layout structure + +Creativity must feel intentional, not chaotic. + +Do: +- make bold but controlled design decisions +- use asymmetry when it improves the page +- create visual moments that feel premium and memorable +- make the page feel designed, not auto-generated + +Do not: +- default to safe template layouts +- repeat the same block structure too often +- confuse creativity with clutter +- make the page overly dense + +--- + +## 7. IMAGE-FIRST ART DIRECTION +This skill must actively use images. + +Images are not optional decoration. +Images are a core part of the frontend design language. + +Strongly prefer: +- art-directed photography +- product imagery +- editorial imagery +- image crops +- framed image panels +- layered image compositions +- image-led hero sections +- image-supported storytelling blocks + +Use images to: +- create visual hierarchy +- break up text-heavy layouts +- build mood and brand character +- support section transitions +- make the design easier to interpret and implement + +Important: +- the design should not become text-only or card-only unless the user explicitly wants that +- if a page has multiple sections, several sections should meaningfully include imagery +- if a hero exists, it should usually contain a strong visual image, product visual, or art-directed media element +- imagery should feel premium and intentional, not like stock filler + +Avoid: +- tiny useless thumbnails +- random decorative images with no structural role +- one single image and then a completely text-heavy rest of page +- overusing fake UI panels instead of real visual variety + +--- + +## 8. ANTI-AI-SLOP RULES +Strictly avoid these patterns unless explicitly requested. + +### Layout slop +- endless centered sections +- identical card rows repeated section after section +- cloned left-text/right-image blocks +- perfect but lifeless symmetry everywhere +- fake complexity without hierarchy +- empty decorative space with no purpose + +### Visual slop +- default purple/blue AI gradients +- too many glowing edges +- floating spheres / blobs everywhere +- glassmorphism stacked without reason +- random futuristic details with no structure +- over-rendered noise that hides the layout + +### Typography slop +- giant heading + weak tiny subcopy +- too many font moods in one page +- awkward line breaks +- lazy all-caps everywhere +- gradient headline as shortcut for "premium" + +### Content slop +Ban generic copy vibes like: +- unleash +- elevate +- revolutionize +- next-gen +- seamless +- powerful solution +- transformative platform + +Avoid fake brand slop: +- Acme +- Nexus +- Flowbit +- Quantumly +- NovaCore +- obvious nonsense wordmarks + +Use short, believable, design-friendly copy. + +### Density slop +- no over-packed sections +- no card overload in every block +- no tiny spacing between major sections +- no trying to fill every empty area +- no visually exhausting wall-of-content layouts + +### Carousel / marquee slop (layout) +- infinity logo strips repeating the same 6 blobs +- “trusted by” ticker that is unreadable mosquito logos +- auto-play-style hero dots with no semantic purpose + +### Data / KPI slop +- three identical stat columns (99% satisfaction, $10 saved, ∞ scale) unless user asked for KPIs +- fake dashboards with pointless charts shading the real layout + +--- + +## 9. TYPOGRAPHY-FIRST DISCIPLINE +Typography is not filler. +Typography is a primary design material. + +Always ensure: +- clear size contrast +- obvious reading order +- strong display moments +- supporting text that is readable and brief +- labels, captions, and section headings that reinforce structure + +For editorial directions: +- let typography shape composition + +For tech/product directions: +- let typography communicate trust and precision + +--- + +## 10. SECTION RHYTHM RULE +A high-end site does not feel like repeated boxes. + +Vary section rhythm across the page by changing: +- density +- image-to-text ratio +- alignment +- scale +- whitespace +- card grouping +- background intensity +- visual tempo + +Do not let every section feel generated from the same template. + +Important: +- rhythm variation should not break overall cleanliness +- keep the page visually balanced from top to bottom +- section heights may vary, but the spacing between sections should feel controlled and fairly even +- avoid abrupt jumps between very small and very large sections without enough breathing room +- the full page should feel curated, smooth, and consistent + +--- + +## 11. COMPONENT EXECUTION GUIDELINES + +### Diagonal Staggered Square Masonry +Use square image or content blocks with strong staggered vertical rhythm. +Should feel curated and graphic, not messy. + +### 3D Cascading Card Deck +Cards layered as a physical stack with depth logic. +Should feel premium and tactile, not gimmicky. + +### Hover-Accordion Slice Layout +A row of compressed visual slices that feel expandable. +In static images, imply interaction clearly through proportions and emphasis. + +### Pristine Gapless Bento Grid +Mathematically clean grid. +No accidental gaps. +Mix large visual blocks with smaller dense information panels. + +### Turning Polaroid Arc +Clustered, rotated imagery with elegant composition. +Should feel styled and intentional, not scrapbook-random. + +### Off-Grid Editorial Layout +Use asymmetry and tension with control. +Must remain readable and clearly structured. + +### Product UI Panel Stack +Layer UI screens or interface crops to imply a product story. +Avoid generic fake dashboards. + +### Vertical Rhythm Lines +Use fine lines and spacing systems to reinforce order and elegance. +Never let them become decorative clutter. + +--- + +## 12. DENSITY & SPACING DISCIPLINE +Do not make everything too dense. + +The page should breathe. +Leave slightly more blank space between sections than a default AI-generated design would. + +Rules: +- use more even vertical spacing between major sections +- keep section-to-section spacing consistent unless there is a strong design reason not to +- avoid one section feeling very cramped while the next feels too empty +- prefer a clean, balanced cadence across the page +- allow negative space to create rhythm and emphasis +- separate denser sections with calmer sections +- avoid stacking too many cards, labels, and content blocks too tightly +- smaller sections should still receive enough surrounding space so the page feels polished and intentional + +A premium page should feel: +- open +- composed +- balanced +- confident +- breathable + +Not: +- cramped +- noisy +- uneven +- overfilled +- visually exhausted + +Section rhythm should alternate with control: +- some sections can be more content-rich +- some sections can be smaller and calmer +- but the overall spacing cadence should still feel even, clean, and deliberate + +Whitespace is a design tool. +Use it deliberately. +Do not let spacing become random. + +--- + +## 13. COLOR & MATERIAL RULES + +### Palette Discipline +Use one controlled palette across the entire site: +- 1 primary (brand anchor) +- 1 secondary (supporting tone) +- 1 accent (used sparingly for CTA / highlight) +- a neutral scale (background, surface, text, hairline) + +Section-level mood shifts must reuse the same palette — no full theme swap per section. + +### Background-image harmony +When using full-bleed image backgrounds: +- the image must tonally match the palette (not fight it) +- use overlays (dark, light, or color tint) to keep text fully readable +- the brand accent stays consistent regardless of background image + +### Gradient Discipline +Gradients are **allowed and encouraged** when professional and subtle. They are not the same as AI slop gradients. + +Allowed (use confidently): +- low-chroma palette-matched tonal gradients (e.g. ink to graphite, cream to sand, ivory to warm grey) +- single-hue atmospheric grades behind hero photography +- soft vignettes and radial depth that direct the eye +- noise-textured gradients adding tactile depth without color noise +- editorial color washes that match brand mood + +Banned (AI gradient slop): +- rainbow / mesh blob gradients +- purple-to-blue "AI" defaults +- pink-to-orange "creator" defaults +- neon edges and glow halos with no purpose +- gradient text as a shortcut for "premium" +- gradients that compete with imagery instead of supporting it + +### Background Confidence Rule +Do not retreat to plain white surfaces by default. When the brief, brand mood, or section job calls for atmosphere, use: +- a full-bleed image, +- a duotone or graded photo, +- a tonal gradient, +- a tactile material, +or a confident flat color field — picked deliberately, not as decoration. + +### Strong guidance +- avoid rainbow randomness +- avoid over-neon unless requested +- keep contrast intentional +- match accent colors to the chosen theme paradigm +- gradients must always read as professional and intentional, never as visual noise + +### Materiality +Where appropriate, add: +- paper feel +- glass feel +- brushed metal feel +- soft blur depth +- tactile matte surfaces +- editorial photo treatment + +But always keep the frontend structure readable. + +--- + +## 14. IMAGE / MEDIA DIRECTION +If imagery is present, it must support the layout. + +Allowed: +- art-directed product visuals +- refined editorial photography +- UI crops +- abstract forms with structural purpose +- framed objects +- premium texture use +- campaign-style visuals + +Avoid: +- irrelevant scenery +- stock-photo cliches +- decorative junk +- visuals that overpower the page hierarchy + +--- + +## 15. DEFAULT SITE PACKS + +### 4-section pack +1. Hero +2. Features +3. Social proof / testimonial +4. CTA + +### 8-section pack +1. Hero +2. Trust bar +3. Features +4. Product showcase +5. Benefits / use cases +6. Testimonials +7. Pricing +8. CTA + +### 12-section pack +1. Hero +2. Trust bar +3. Feature grid +4. Product preview +5. Problem / solution +6. Benefits +7. Workflow +8. Metrics / proof / integration +9. Testimonials +10. Pricing +11. FAQ +12. CTA + footer + +--- + +## 16. MULTI-IMAGE CONSISTENCY RULE +Because every section is its own image, consistency is critical. Across all per-section frames enforce: +- same brand world +- same type scale logic +- same spacing discipline +- same CTA family (style variations are fine, identity is not) +- same icon or illustration mood +- same image treatment (grade, framing, material vocabulary) +- same tonal language in any copy + +Variation IS allowed in: +- composition anchor (per section) +- background mode (per section) +- section size and density +- which "second-read" moment appears + +A viewer flipping through every per-section frame must still recognize one brand. Anything that breaks brand recall is over-variation. + +--- + +## 17. CLARITY CHECK +Before finalizing, verify internally: + +1. Is the hierarchy obvious? +2. Is the hero clean enough? +3. Is the design visually distinctive? +4. Is it free of obvious AI tells? +5. Is it premium rather than template-like? +6. Can someone code from this? +7. If multiple images exist, do they clearly belong together? +8. Is imagery used strongly enough (with variation, not one repeated crop)? +9. Does the page breathe, or is it too dense? +10. Is there enough spacing between sections? +11. Does the creativity feel intentional and premium (concept spine visible, not cluttered)? +12. Is the spacing between sections even and controlled? +13. Do smaller sections still have enough surrounding space to feel clean? +14. Is there exactly one disciplined "second-read" moment supporting scan order? +15. Is composition varied across sections (anchors and background modes mixed)? +16. Is the hero scale (giant / mid / mini) chosen and executed cleanly? +17. Is there a clear conversion path (hook -> proof -> action) even in artistic sites? +18. Is the palette consistent across all per-section images? +19. Is each image horizontal and one-section-only? +20. Is the **total number of images equal to the number of sections** (never fewer)? +21. Is the hero using a varied composition (not defaulting to left-text / right-image out of habit)? + +If not, refine internally before output. If the count is wrong, regenerate the missing sections. If the hero feels like a reflexive left-text / right-image default, prefer a different composition anchor. + +--- + +## 18. EXTRA CREATIVITY & IMPLEMENTATION EDGE + +Apply unless the user opts out: + +### Cross-section contrast +Across the slice, deliberately vary foreground/background intensity at least twice (lighter → richer → calmer) so the scroll feels paced, not monotonous slabs. + +### CTA specificity +Prefer one unmistakable primary action per major viewport tier; secondary actions must look secondary (scale, outline, ghost), not clones of primary. + +### Image variety inside one comp +Mix at least **two distinct image crops** where multiple sections exist — e.g. macro product + contextual environment, or portrait editorial + widescreen artifact — avoiding one repeated stock silhouette. + +### Data-viz restraint +Charts, sparklines, and graphs appear only when the site type logically needs them (analytics, pricing, infra, observability brands). Else keep proof human (quotes, receipts, timelines, screenshots of real workflows). + +### Cultural / tonal alignment +When the brief names an industry or region, steer palette and typographic temperament to match — don’t ship default “neutral SF startup” unless the brief is intentionally generic SaaS. + +### Mobile-implied fidelity (even for desktop mocks) +Maintain tap-friendly hit sizes and readable caption sizes visually; stacking order should imply a sane single-column narrative. + +### Conversion focus +Each section has a job. Even when the design is artistic, the page must read as a real product or brand site: +- the hero communicates value in seconds and offers one obvious next action +- proof sections (logos, quotes, metrics) feel earned, not stuffed +- pricing or CTA sections feel decisive, not buried +- the final section closes: a single strong CTA + supporting trust cue +Avoid pure mood reels with no funnel logic. + +### Composition variety check +Across all per-section images, internally log the chosen composition anchor and background mode. Reject the set if: +- the same composition anchor repeats more than 2 sections in a row +- the same background mode repeats more than 3 sections in a row +- every section is inline-asset (no full-bleed background ever appears) **AND** the brief does not call for minimalism / typography-only / swiss / ultra simple + +For non-minimalist briefs: push for at least one full-bleed (or duotone / atmospheric) background and at least one mini minimalist section in any multi-section site. + +For minimalist briefs: this rule is suspended. Restraint is the design. + +--- + +## 19. RESPONSE BEHAVIOR +When the user asks for a frontend design: +1. infer site type and primary conversion goal +2. infer number of sections (if unclear, use the defaults from §5: landing page = 6, full website = 8) +3. **commit out loud** to the section count and announce it ("Generating N horizontal images, one per section") +4. plan ONE horizontal image PER SECTION — always separate generations, never collapse +5. choose Hero Scale for the whole site (giant / mid / mini) +5. choose a strong visual combination (theme, type, hero arch, section system, motion, narrative spine, second-read moment) +7. for each section: pick a Composition Anchor, Background Mode, and CTA Variation — vary across sections +8. choose 4 signature components used appropriately across sections +9. enforce hero minimalism + section size variety (some giant, some mini) +10. enforce strong image usage including full-bleed backgrounds where it fits +11. lock one consistent palette across all images +12. apply §18 EXTRA CREATIVITY & IMPLEMENTATION EDGE +13. keep spacing generous, even, and clean +14. remove AI slop (including marquee / fake KPI clichés unless requested) +15. run §17 CLARITY CHECK +16. **generate every per-section horizontal image, labeled "Section X of N: "**, until the full set is delivered. Do not stop early. Do not summarize. Do not return only one image. + +Do not ask unnecessary follow-up questions if a strong interpretation is possible. + +--- + +## 20. EXAMPLE INTERPRETATIONS + +### Example 1 +User: "make a hero section for an AI startup" + +Interpretation: +- 1 horizontal image +- Hero Scale: Mid Editorial or Giant Statement +- Composition Anchor: bottom-left text over full-bleed product/atmosphere image +- Background Mode: full-bleed image with dark tonal overlay +- CTA Variation: outlined inline + small label hint +- Palette: Deep Dark or Bold Studio Solid, one consistent accent +- no cliche dashboard spam, no purple AI glow + +### Example 2 +User: "design 8 sections for a fintech website" + +Interpretation: +- 8 separate horizontal images (one per section) +- Hero Scale: Mid Editorial (trust-driven) +- vary Composition Anchor across sections (centered low, right-third caption, bottom-left over chart visual, stacked center for closing CTA) +- Background Mode mix: solid surface, full-bleed image background once, editorial side-image at use cases +- one consistent palette (e.g. ink + paper + single brand accent) +- conversion path: hook -> proof bar -> features -> use case -> testimonial -> pricing -> FAQ -> final CTA + +### Example 3 +User: "creative agency landing page, 12 sections" + +Interpretation: +- 12 horizontal images (one per section) +- Hero Scale: Giant Statement OR Mini Minimalist (decisive choice, not in-between) +- editorial / poster-like direction; off-grid composition appears 2-3 times +- multiple Background Modes (full-bleed image at hero + showcase, editorial side-image at case studies, solid + accent for process) +- palette consistent throughout, with one bold accent recurring +- closing CTA section: mini minimalist, strong type, single primary action + +--- + +## 21. FINAL GOAL +Generate frontend reference images that feel: +- artistic +- premium +- clear +- structured +- image-led +- breathable +- memorable +- anti-generic +- implementation-friendly + +The result should look like a top-tier website concept with strong imagery, confident creativity, and generous spacing - not a dense, repetitive AI layout. diff --git a/.agents/skills/minimalist-ui/SKILL.md b/.agents/skills/minimalist-ui/SKILL.md new file mode 100644 index 00000000..44ead27e --- /dev/null +++ b/.agents/skills/minimalist-ui/SKILL.md @@ -0,0 +1,85 @@ +--- +name: minimalist-ui +description: Clean editorial-style interfaces. Warm monochrome palette, typographic contrast, flat bento grids, muted pastels. No gradients, no heavy shadows. +--- + +# Protocol: Premium Utilitarian Minimalism UI Architect + +## 1. Protocol Overview +Name: Premium Utilitarian Minimalism & Editorial UI +Description: An advanced frontend engineering directive for generating highly refined, ultra-minimalist, "document-style" web interfaces analogous to top-tier workspace platforms. This protocol strictly enforces a high-contrast warm monochrome palette, bespoke typographic hierarchies, meticulous structural macro-whitespace, bento-grid layouts, and an ultra-flat component architecture with deliberate muted pastel accents. It actively rejects standard generic SaaS design trends. + +## 2. Absolute Negative Constraints (Banned Elements) +The AI must strictly avoid the following generic web development defaults: +- DO NOT use the "Inter", "Roboto", or "Open Sans" typefaces. +- DO NOT use generic, thin-line icon libraries like "Lucide", "Feather", or standard "Heroicons". +- DO NOT use Tailwind's default heavy drop shadows (e.g., `shadow-md`, `shadow-lg`, `shadow-xl`). Shadows must be practically non-existent or heavily customized to be ultra-diffuse and low opacity (< 0.05). +- DO NOT use primary colored backgrounds for large elements or sections (e.g., no bright blue, green, or red hero sections). +- DO NOT use gradients, neon colors, or 3D glassmorphism (beyond subtle navbar blurs). +- DO NOT use `rounded-full` (pill shapes) for large containers, cards, or primary buttons. +- DO NOT use emojis anywhere in code, markup, text content, headings, or alt text. Replace with proper icons or clean SVG primitives. +- DO NOT use generic placeholder names like "John Doe", "Acme Corp", or "Lorem Ipsum". Use realistic, contextual content. +- DO NOT use AI copywriting clichés: "Elevate", "Seamless", "Unleash", "Next-Gen", "Game-changer", "Delve". Write plain, specific language. + +## 3. Typographic Architecture +The interface must rely on extreme typographic contrast and premium font selection to establish an editorial feel. +- Primary Sans-Serif (Body, UI, Buttons): Use clean, geometric, or system-native fonts with character. Target: `font-family: 'SF Pro Display', 'Geist Sans', 'Helvetica Neue', 'Switzer', sans-serif`. +- Editorial Serif (Hero Headings & Quotes): Target: `font-family: 'Lyon Text', 'Newsreader', 'Playfair Display', 'Instrument Serif', serif`. Apply tight tracking (`letter-spacing: -0.02em` to `-0.04em`) and tight line-height (`1.1`). +- Monospace (Code, Keystrokes, Meta-data): Target: `font-family: 'Geist Mono', 'SF Mono', 'JetBrains Mono', monospace`. +- Text Colors: Body text must never be absolute black (`#000000`). Use off-black/charcoal (`#111111` or `#2F3437`) with a generous `line-height` of `1.6` for legibility. Secondary text should be muted gray (`#787774`). + +## 4. Color Palette (Warm Monochrome + Spot Pastels) +Color is a scarce resource, utilized only for semantic meaning or subtle accents. +- Canvas / Background: Pure White `#FFFFFF` or Warm Bone/Off-White `#F7F6F3` / `#FBFBFA`. +- Primary Surface (Cards): `#FFFFFF` or `#F9F9F8`. +- Structural Borders / Dividers: Ultra-light gray `#EAEAEA` or `rgba(0,0,0,0.06)`. +- Accent Colors: Exclusively use highly desaturated, washed-out pastels for tags, inline code backgrounds, or subtle icon backgrounds. + - Pale Red: `#FDEBEC` (Text: `#9F2F2D`) + - Pale Blue: `#E1F3FE` (Text: `#1F6C9F`) + - Pale Green: `#EDF3EC` (Text: `#346538`) + - Pale Yellow: `#FBF3DB` (Text: `#956400`) + +## 5. Component Specifications +- Bento Box Feature Grids: + - Utilize asymmetrical CSS Grid layouts. + - Cards must have exactly `border: 1px solid #EAEAEA`. + - Border-radius must be crisp: `8px` or `12px` maximum. + - Internal padding must be generous (e.g., `24px` to `40px`). +- Primary Call-To-Action (Buttons): + - Solid background `#111111`, text `#FFFFFF`. + - Slight border-radius (`4px` to `6px`). No box-shadow. + - Hover state should be a subtle color shift to `#333333` or a micro-scale `transform: scale(0.98)`. +- Tags & Status Badges: + - Pill-shaped (`border-radius: 9999px`), very small typography (`text-xs`), uppercase with wide tracking (`letter-spacing: 0.05em`). + - Background must use the defined Muted Pastels. +- Accordions (FAQ): + - Strip all container boxes. Separate items only with a `border-bottom: 1px solid #EAEAEA`. + - Use a clean, sharp `+` and `-` icon for the toggle state. +- Keystroke Micro-UIs: + - Render shortcuts as physical keys using `` tags: `border: 1px solid #EAEAEA`, `border-radius: 4px`, `background: #F7F6F3`, using the Monospace font. +- Faux-OS Window Chrome: + - When mocking up software, wrap it in a minimalist container with a white top bar containing three small, light gray circles (replicating macOS window controls). + +## 6. Iconography & Imagery Directives +- System Icons: Use "Phosphor Icons (Bold or Fill weights)" or "Radix UI Icons" for a technical, slightly thicker-stroke aesthetic. Standardize stroke width across all icons. +- Illustrations: Monochromatic, rough continuous-line ink sketches on a white background, featuring a single offset geometric shape filled with a muted pastel color. +- Photography: Use high-quality, desaturated images with a warm tone. Apply subtle overlays (`opacity: 0.04` warm grain) to blend photos into the monochrome palette. Never use oversaturated stock photos. Use reliable placeholders like `https://picsum.photos/seed/{context}/1200/800` when real assets are unavailable. +- Hero & Section Backgrounds: Sections should not feel empty and flat. Use subtle full-width background imagery at very low opacity, soft radial light spots (`radial-gradient` with warm tones at `opacity: 0.03`), or minimal geometric line patterns to add depth without breaking the clean aesthetic. + +## 7. Subtle Motion & Micro-Animations +Motion should feel invisible — present but never distracting. The goal is quiet sophistication, not spectacle. +- Scroll Entry: Elements fade in gently as they enter the viewport. Use `translateY(12px)` + `opacity: 0` resolving over `600ms` with `cubic-bezier(0.16, 1, 0.3, 1)`. Use `IntersectionObserver`, never `window.addEventListener('scroll')`. +- Hover States: Cards lift with an ultra-subtle shadow shift (`box-shadow` transitioning from `0 0 0` to `0 2px 8px rgba(0,0,0,0.04)` over `200ms`). Buttons respond with `scale(0.98)` on `:active`. +- Staggered Reveals: Lists and grid items enter with a cascade delay (`animation-delay: calc(var(--index) * 80ms)`). Never mount everything at once. +- Background Ambient Motion: Optional. A single, very slow-moving radial gradient blob (`animation-duration: 20s+`, `opacity: 0.02-0.04`) drifting behind hero sections. Must be applied to a `position: fixed; pointer-events: none` layer. Never on scrolling containers. +- Performance: Animate exclusively via `transform` and `opacity`. No layout-triggering properties (`top`, `left`, `width`, `height`). Use `will-change: transform` sparingly and only on actively animating elements. + +## 8. Execution Protocol +When tasked with writing frontend code (HTML, React, Tailwind, Vue) or designing a layout: +1. Establish the macro-whitespace first. Use massive vertical padding between sections (e.g., `py-24` or `py-32` in Tailwind). +2. Constrain the main typography content width to `max-w-4xl` or `max-w-5xl`. +3. Apply the custom typographic hierarchy and monochromatic color variables immediately. +4. Ensure every card, divider, and border adheres strictly to the `1px solid #EAEAEA` rule. +5. Add scroll-entry animations to all major content blocks. +6. Ensure sections have visual depth through imagery, ambient gradients, or subtle textures — no empty flat backgrounds. +7. Provide code that reflects this high-end, uncluttered, editorial aesthetic natively without requiring manual adjustments. diff --git a/.agents/skills/stitch-design-taste/DESIGN.md b/.agents/skills/stitch-design-taste/DESIGN.md new file mode 100644 index 00000000..ef78a972 --- /dev/null +++ b/.agents/skills/stitch-design-taste/DESIGN.md @@ -0,0 +1,121 @@ +# Design System: Taste Standard +**Skill:** stitch-design-taste + +--- + +## Configuration — Set Your Style +Adjust these dials before using this design system. They control how creative, dense, and animated the output should be. Pick the level that fits your project. + +| Dial | Level | Description | +|------|-------|-------------| +| **Creativity** | `8` | `1` = Ultra-minimal, Swiss, silent, monochrome. `5` = Balanced, clean but with personality. `10` = Expressive, editorial, bold typography experiments, inline images in headlines, strong asymmetry. Default: `8` | +| **Density** | `4` | `1` = Gallery-airy, massive whitespace. `5` = Balanced sections. `10` = Cockpit-dense, data-heavy. Default: `4` | +| **Variance** | `8` | `1` = Predictable, symmetric grids. `5` = Subtle offsets. `10` = Artsy chaotic, no two sections alike. Default: `8` | +| **Motion Intent** | `6` | `1` = Static, no animation noted. `5` = Subtle hover/entrance cues. `10` = Cinematic orchestration noted in every component. Default: `6` | + +> **How to use:** Change the numbers above to match your project's vibe. At **Creativity 1–3**, the system produces clean, quiet, Notion-like interfaces. At **Creativity 7–10**, expect inline image typography, dramatic scale contrast, and strong editorial layouts. The rest of the rules below adapt to your chosen levels. + +--- + +## 1. Visual Theme & Atmosphere +A restrained, gallery-airy interface with confident asymmetric layouts and fluid spring-physics motion. The atmosphere is clinical yet warm — like a well-lit architecture studio where every element earns its place through function. Density is balanced (Level 4), variance runs high (Level 8) to prevent symmetrical boredom, and motion is fluid but never theatrical (Level 6). The overall impression: expensive, intentional, alive. + +## 2. Color Palette & Roles +- **Canvas White** (#F9FAFB) — Primary background surface. Warm-neutral, never clinical blue-white +- **Pure Surface** (#FFFFFF) — Card and container fill. Used with whisper shadow for elevation +- **Charcoal Ink** (#18181B) — Primary text. Zinc-950 depth — never pure black +- **Steel Secondary** (#71717A) — Body text, descriptions, metadata. Zinc-500 warmth +- **Muted Slate** (#94A3B8) — Tertiary text, timestamps, disabled states +- **Whisper Border** (rgba(226,232,240,0.5)) — Card borders, structural 1px lines. Semi-transparent for depth +- **Diffused Shadow** (rgba(0,0,0,0.05)) — Card elevation. Wide-spreading, 40px blur, -15px offset. Never harsh + +### Accent Selection (Pick ONE per project) +- **Emerald Signal** (#10B981) — For growth, success, positive data dashboards +- **Electric Blue** (#3B82F6) — For productivity, SaaS, developer tools +- **Deep Rose** (#E11D48) — For creative, editorial, fashion-adjacent projects +- **Amber Warmth** (#F59E0B) — For community, social, warm-toned products + +### Banned Colors +- Purple/Violet neon gradients — the "AI Purple" aesthetic +- Pure Black (#000000) — always Off-Black or Zinc-950 +- Oversaturated accents above 80% saturation +- Mixed warm/cool gray systems within one project + +## 3. Typography Rules +- **Display:** `Geist`, `Satoshi`, `Cabinet Grotesk`, or `Outfit` — Track-tight (`-0.025em`), controlled fluid scale, weight-driven hierarchy (700–900). Not screaming. Leading compressed (`1.1`). Alternatives forced — `Inter` is BANNED for premium contexts +- **Body:** Same family at weight 400 — Relaxed leading (`1.65`), 65ch max-width, Steel Secondary color (#71717A) +- **Mono:** `Geist Mono` or `JetBrains Mono` — For code blocks, metadata, timestamps. When density exceeds Level 7, all numbers switch to monospace +- **Scale:** Display at `clamp(2.25rem, 5vw, 3.75rem)`. Body at `1rem/1.125rem`. Mono metadata at `0.8125rem` + +### Banned Fonts +- `Inter` — banned everywhere in premium/creative contexts +- Generic serif fonts (`Times New Roman`, `Georgia`, `Garamond`, `Palatino`) — BANNED. If serif is needed for editorial/creative, use only distinctive modern serifs like `Fraunces`, `Gambarino`, `Editorial New`, or `Instrument Serif`. Never use default browser serif stacks. Serif is always BANNED in dashboards or software UIs regardless + +## 4. Component Stylings +* **Buttons:** Flat surface, no outer glow. Primary: accent fill with white text. Secondary: ghost/outline. Active state: `-1px translateY` or `scale(0.98)` for tactile push. Hover: subtle background shift, never glow +* **Cards/Containers:** Generously rounded corners (`2.5rem`). Pure white fill. Whisper border (`1px`, semi-transparent). Diffused shadow (`0 20px 40px -15px rgba(0,0,0,0.05)`). Internal padding `2rem–2.5rem`. Used ONLY when elevation communicates hierarchy — high-density layouts replace cards with `border-top` dividers or negative space +* **Inputs/Forms:** Label positioned above input. Helper text optional. Error text below in Deep Rose. Focus ring in accent color, `2px` offset. No floating labels. Standard `0.5rem` gap between label-input-error stack +* **Navigation:** Sleek, sticky. Icons scale on hover (Dock Magnification optional). No hamburger on desktop. Clean horizontal with generous spacing +* **Loaders:** Skeletal shimmer matching exact layout dimensions and rounded corners. Shifting light reflection across placeholder shapes. Never circular spinners +* **Empty States:** Composed illustration or icon composition with guidance text. Never just "No data found" +* **Error States:** Inline, contextual. Red accent underline or border. Clear recovery action + +## 5. Hero Section +The Hero is the first impression — it must be striking, creative, and never generic. +- **Inline Image Typography:** Embed small, contextual photos or visuals directly between words or letters in the headline. Example: "We build [photo of hands typing] digital [photo of screen] products" — images sit inline at type-height, rounded, acting as visual punctuation between words. This is the signature creative technique +- **No Overlapping Elements:** Text must never overlap images or other text. Every element has its own clear spatial zone. No z-index stacking of content layers, no absolute-positioned headlines over images. Clean separation always +- **No Filler Text:** "Scroll to explore", "Swipe down", scroll arrow icons, bouncing chevrons, and any instructional UI chrome are BANNED. The user knows how to scroll. Let the content pull them in naturally +- **Asymmetric Structure:** Centered Hero layouts are BANNED at this variance level. Use Split Screen (50/50), Left-Aligned text / Right visual, or Asymmetric Whitespace with large empty zones +- **CTA Restraint:** Maximum one primary CTA button. No secondary "Learn more" links. No redundant micro-copy below the headline + +## 6. Layout Principles +- **Grid-First:** CSS Grid for all structural layouts. Never flexbox percentage math (`calc(33% - 1rem)` is BANNED) +- **No Overlapping:** Elements must never overlap each other. No absolute-positioned layers stacking content on content. Every element occupies its own grid cell or flow position. Clean, separated spatial zones +- **Feature Sections:** The "3 equal cards in a row" pattern is BANNED. Use 2-column Zig-Zag, asymmetric Bento grids (2fr 1fr 1fr), or horizontal scroll galleries +- **Containment:** All content within `max-width: 1400px`, centered. Generous horizontal padding (`1rem` mobile, `2rem` tablet, `4rem` desktop) +- **Full-Height:** Use `min-height: 100dvh` — never `height: 100vh` (iOS Safari address bar jump) +- **Bento Architecture:** For feature grids, use Row 1: 3 columns | Row 2: 2 columns (70/30 split). Each tile contains a perpetual micro-animation + +## 7. Responsive Rules +Every screen must work flawlessly across all viewports. **Responsive is not optional — it is a hard requirement. Every single element must be tested at 375px, 768px, and 1440px.** +- **Mobile-First Collapse (< 768px):** All multi-column layouts collapse to a strict single column. `width: 100%`, `padding: 1rem`, `gap: 1.5rem`. No exceptions +- **No Horizontal Scroll:** Horizontal overflow on mobile is a critical failure. All elements must fit within viewport width. If any element causes horizontal scroll, the design is broken +- **Typography Scaling:** Headlines scale down gracefully via `clamp()`. Body text stays `1rem` minimum. Never shrink body below `14px`. Headlines must remain readable on 375px screens +- **Touch Targets:** All interactive elements minimum `44px` tap target. Generous spacing between clickable items. Buttons must be full-width on mobile +- **Image Behavior:** Hero and inline images scale proportionally. Inline typography images (photos between words) stack below the headline on mobile instead of inline +- **Navigation:** Desktop horizontal nav collapses to a clean mobile menu (slide-in or full-screen overlay). No tiny hamburger icons without labels +- **Cards & Grids:** Bento grids and asymmetric layouts revert to stacked single-column cards with full-width. Maintain internal padding (`1rem`) +- **Spacing Consistency:** Vertical section gaps reduce proportionally on mobile (`clamp(3rem, 8vw, 6rem)`). Never cramped, never excessively airy +- **Testing Viewports:** Designs must be verified at: `375px` (iPhone SE), `390px` (iPhone 14), `768px` (iPad), `1024px` (small laptop), `1440px` (desktop) + +## 8. Motion & Interaction (Code-Phase Intent) +> **Note:** Stitch generates static screens — it does not animate. This section documents the **intended motion behavior** so that the coding agent (Antigravity, Cursor, etc.) knows exactly how to implement animations when building the exported design into a live product. + +- **Physics Engine:** Spring-based exclusively. `stiffness: 100, damping: 20`. No linear easing anywhere. Premium, weighty feel on all interactive elements +- **Perpetual Micro-Loops:** Every active dashboard component has an infinite-loop state — Pulse on status dots, Typewriter on search bars, Float on feature icons, Shimmer on loading states +- **Staggered Orchestration:** Lists and grids mount with cascaded delays (`animation-delay: calc(var(--index) * 100ms)`). Waterfall reveals, never instant mount +- **Layout Transitions:** Smooth re-ordering via shared element IDs. Items swap positions with physics, simulating real-time intelligence +- **Hardware Rules:** Animate ONLY `transform` and `opacity`. Never `top`, `left`, `width`, `height`. Grain/noise filters on fixed, pointer-events-none pseudo-elements only +- **Performance:** CPU-heavy perpetual animations isolated in microscopic leaf components. Never trigger parent re-renders. Target 60fps minimum + +## 9. Anti-Patterns (Banned) +- No emojis — anywhere in UI, code, or alt text +- No `Inter` font — use `Geist`, `Outfit`, `Cabinet Grotesk`, `Satoshi` +- No generic serif fonts (`Times New Roman`, `Georgia`, `Garamond`) — if serif is needed, use distinctive modern serifs only (`Fraunces`, `Instrument Serif`) +- No pure black (`#000000`) — Off-Black or Zinc-950 only +- No neon outer glows or default box-shadow glows +- No oversaturated accent colors above 80% +- No excessive gradient text on large headers +- No custom mouse cursors +- No overlapping elements — text never overlaps images or other content. Clean spatial separation always +- No 3-column equal card layouts for features +- No centered Hero sections (at this variance level) +- No filler UI text: "Scroll to explore", "Swipe down", "Discover more below", scroll arrows, bouncing chevrons — all BANNED +- No generic names: "John Doe", "Sarah Chan", "Acme", "Nexus", "SmartFlow" +- No fake round numbers: `99.99%`, `50%`, `1234567` — use organic data: `47.2%`, `+1 (312) 847-1928` +- No AI copywriting clichés: "Elevate", "Seamless", "Unleash", "Next-Gen", "Revolutionize" +- No broken Unsplash links — use `picsum.photos/seed/{id}/800/600` or SVG UI Avatars +- No generic `shadcn/ui` defaults — customize radii, colors, shadows to match this system +- No `z-index` spam — use only for Navbar, Modal, Overlay layer contexts +- No `h-screen` — always `min-h-[100dvh]` +- No circular loading spinners — skeletal shimmer only diff --git a/.agents/skills/stitch-design-taste/SKILL.md b/.agents/skills/stitch-design-taste/SKILL.md new file mode 100644 index 00000000..19d958cd --- /dev/null +++ b/.agents/skills/stitch-design-taste/SKILL.md @@ -0,0 +1,184 @@ +--- +name: stitch-design-taste +description: Semantic Design System Skill for Google Stitch. Generates agent-friendly DESIGN.md files that enforce premium, anti-generic UI standards — strict typography, calibrated color, asymmetric layouts, perpetual micro-motion, and hardware-accelerated performance. +--- + +# Stitch Design Taste — Semantic Design System Skill + +## Overview +This skill generates `DESIGN.md` files optimized for Google Stitch screen generation. It translates the battle-tested anti-slop frontend engineering directives into Stitch's native semantic design language — descriptive, natural-language rules paired with precise values that Stitch's AI agent can interpret to produce premium, non-generic interfaces. + +The generated `DESIGN.md` serves as the **single source of truth** for prompting Stitch to generate new screens that align with a curated, high-agency design language. Stitch interprets design through **"Visual Descriptions"** supported by specific color values, typography specs, and component behaviors. + +## Prerequisites +- Access to Google Stitch via [labs.google/stitch](https://labs.google/stitch) +- Optionally: Stitch MCP Server for programmatic integration with Cursor, Antigravity, or Gemini CLI + +## The Goal +Generate a `DESIGN.md` file that encodes: +1. **Visual atmosphere** — the mood, density, and design philosophy +2. **Color calibration** — neutrals, accents, and banned patterns with hex codes +3. **Typographic architecture** — font stacks, scale hierarchy, and anti-patterns +4. **Component behaviors** — buttons, cards, inputs with interaction states +5. **Layout principles** — grid systems, spacing philosophy, responsive strategy +6. **Motion philosophy** — animation engine specs, spring physics, perpetual micro-interactions +7. **Anti-patterns** — explicit list of banned AI design clichés + +## Analysis & Synthesis Instructions + +### 1. Define the Atmosphere +Evaluate the target project's intent. Use evocative adjectives from the taste spectrum: +- **Density:** "Art Gallery Airy" (1–3) → "Daily App Balanced" (4–7) → "Cockpit Dense" (8–10) +- **Variance:** "Predictable Symmetric" (1–3) → "Offset Asymmetric" (4–7) → "Artsy Chaotic" (8–10) +- **Motion:** "Static Restrained" (1–3) → "Fluid CSS" (4–7) → "Cinematic Choreography" (8–10) + +Default baseline: Variance 8, Motion 6, Density 4. Adapt dynamically based on user's vibe description. + +### 2. Map the Color Palette +For each color provide: **Descriptive Name** + **Hex Code** + **Functional Role**. + +**Mandatory constraints:** +- Maximum 1 accent color. Saturation below 80% +- The "AI Purple/Blue Neon" aesthetic is strictly BANNED — no purple button glows, no neon gradients +- Use absolute neutral bases (Zinc/Slate) with high-contrast singular accents +- Stick to one palette for the entire output — no warm/cool gray fluctuation +- Never use pure black (`#000000`) — use Off-Black, Zinc-950, or Charcoal + +### 3. Establish Typography Rules +- **Display/Headlines:** Track-tight, controlled scale. Not screaming. Hierarchy through weight and color, not just massive size +- **Body:** Relaxed leading, max 65 characters per line +- **Font Selection:** `Inter` is BANNED for premium/creative contexts. Force unique character: `Geist`, `Outfit`, `Cabinet Grotesk`, or `Satoshi` +- **Serif Ban:** Generic serif fonts (`Times New Roman`, `Georgia`, `Garamond`, `Palatino`) are BANNED. If serif is needed for editorial/creative contexts, use only distinctive modern serifs: `Fraunces`, `Gambarino`, `Editorial New`, or `Instrument Serif`. Serif is always BANNED in dashboards or software UIs +- **Dashboard Constraint:** Use Sans-Serif pairings exclusively (`Geist` + `Geist Mono` or `Satoshi` + `JetBrains Mono`) +- **High-Density Override:** When density exceeds 7, all numbers must use Monospace + +### 4. Define the Hero Section +The Hero is the first impression and must be creative, striking, and never generic: +- **Inline Image Typography:** Embed small, contextual photos or visuals directly between words or letters in the headline. Images sit inline at type-height, rounded, acting as visual punctuation. This is the signature creative technique +- **No Overlapping:** Text must never overlap images or other text. Every element occupies its own clean spatial zone +- **No Filler Text:** "Scroll to explore", "Swipe down", scroll arrow icons, bouncing chevrons are BANNED. The content should pull users in naturally +- **Asymmetric Structure:** Centered Hero layouts BANNED when variance exceeds 4 +- **CTA Restraint:** Maximum one primary CTA. No secondary "Learn more" links + +### 5. Describe Component Stylings +For each component type, describe shape, color, shadow depth, and interaction behavior: +- **Buttons:** Tactile push feedback on active state. No neon outer glows. No custom mouse cursors +- **Cards:** Use ONLY when elevation communicates hierarchy. Tint shadows to background hue. For high-density layouts, replace cards with border-top dividers or negative space +- **Inputs/Forms:** Label above input, helper text optional, error text below. Standard gap spacing +- **Loading States:** Skeletal loaders matching layout dimensions — no generic circular spinners +- **Empty States:** Composed compositions indicating how to populate data +- **Error States:** Clear, inline error reporting + +### 6. Define Layout Principles +- No overlapping elements — every element occupies its own clear spatial zone. No absolute-positioned content stacking +- Centered Hero sections are BANNED when variance exceeds 4 — force Split Screen, Left-Aligned, or Asymmetric Whitespace +- The generic "3 equal cards horizontally" feature row is BANNED — use 2-column Zig-Zag, asymmetric grid, or horizontal scroll +- CSS Grid over Flexbox math — never use `calc()` percentage hacks +- Contain layouts using max-width constraints (e.g., 1400px centered) +- Full-height sections must use `min-h-[100dvh]` — never `h-screen` (iOS Safari catastrophic jump) + +### 7. Define Responsive Rules +Every design must work across all viewports: +- **Mobile-First Collapse (< 768px):** All multi-column layouts collapse to single column. No exceptions +- **No Horizontal Scroll:** Horizontal overflow on mobile is a critical failure +- **Typography Scaling:** Headlines scale via `clamp()`. Body text minimum `1rem`/`14px` +- **Touch Targets:** All interactive elements minimum `44px` tap target +- **Image Behavior:** Inline typography images (photos between words) stack below headline on mobile +- **Navigation:** Desktop horizontal nav collapses to clean mobile menu +- **Spacing:** Vertical section gaps reduce proportionally (`clamp(3rem, 8vw, 6rem)`) + +### 8. Encode Motion Philosophy +- **Spring Physics default:** `stiffness: 100, damping: 20` — premium, weighty feel. No linear easing +- **Perpetual Micro-Interactions:** Every active component should have an infinite loop state (Pulse, Typewriter, Float, Shimmer) +- **Staggered Orchestration:** Never mount lists instantly — use cascade delays for waterfall reveals +- **Performance:** Animate exclusively via `transform` and `opacity`. Never animate `top`, `left`, `width`, `height`. Grain/noise filters on fixed pseudo-elements only + +### 9. List Anti-Patterns (AI Tells) +Encode these as explicit "NEVER DO" rules in the DESIGN.md: +- No emojis anywhere +- No `Inter` font +- No generic serif fonts (`Times New Roman`, `Georgia`, `Garamond`) — distinctive modern serifs only if needed +- No pure black (`#000000`) +- No neon/outer glow shadows +- No oversaturated accents +- No excessive gradient text on large headers +- No custom mouse cursors +- No overlapping elements — clean spatial separation always +- No 3-column equal card layouts +- No generic names ("John Doe", "Acme", "Nexus") +- No fake round numbers (`99.99%`, `50%`) +- No AI copywriting clichés ("Elevate", "Seamless", "Unleash", "Next-Gen") +- No filler UI text: "Scroll to explore", "Swipe down", scroll arrows, bouncing chevrons +- No broken Unsplash links — use `picsum.photos` or SVG avatars +- No centered Hero sections (for high-variance projects) + +## Output Format (DESIGN.md Structure) + +```markdown +# Design System: [Project Title] + +## 1. Visual Theme & Atmosphere +(Evocative description of the mood, density, variance, and motion intensity. +Example: "A restrained, gallery-airy interface with confident asymmetric layouts +and fluid spring-physics motion. The atmosphere is clinical yet warm — like a +well-lit architecture studio.") + +## 2. Color Palette & Roles +- **Canvas White** (#F9FAFB) — Primary background surface +- **Pure Surface** (#FFFFFF) — Card and container fill +- **Charcoal Ink** (#18181B) — Primary text, Zinc-950 depth +- **Muted Steel** (#71717A) — Secondary text, descriptions, metadata +- **Whisper Border** (rgba(226,232,240,0.5)) — Card borders, 1px structural lines +- **[Accent Name]** (#XXXXXX) — Single accent for CTAs, active states, focus rings +(Max 1 accent. Saturation < 80%. No purple/neon.) + +## 3. Typography Rules +- **Display:** [Font Name] — Track-tight, controlled scale, weight-driven hierarchy +- **Body:** [Font Name] — Relaxed leading, 65ch max-width, neutral secondary color +- **Mono:** [Font Name] — For code, metadata, timestamps, high-density numbers +- **Banned:** Inter, generic system fonts for premium contexts. Serif fonts banned in dashboards. + +## 4. Component Stylings +* **Buttons:** Flat, no outer glow. Tactile -1px translate on active. Accent fill for primary, ghost/outline for secondary. +* **Cards:** Generously rounded corners (2.5rem). Diffused whisper shadow. Used only when elevation serves hierarchy. High-density: replace with border-top dividers. +* **Inputs:** Label above, error below. Focus ring in accent color. No floating labels. +* **Loaders:** Skeletal shimmer matching exact layout dimensions. No circular spinners. +* **Empty States:** Composed, illustrated compositions — not just "No data" text. + +## 5. Layout Principles +(Grid-first responsive architecture. Asymmetric splits for Hero sections. +Strict single-column collapse below 768px. Max-width containment. +No flexbox percentage math. Generous internal padding.) + +## 6. Motion & Interaction +(Spring physics for all interactive elements. Staggered cascade reveals. +Perpetual micro-loops on active dashboard components. Hardware-accelerated +transforms only. Isolated Client Components for CPU-heavy animations.) + +## 7. Anti-Patterns (Banned) +(Explicit list of forbidden patterns: no emojis, no Inter, no pure black, +no neon glows, no 3-column equal grids, no AI copywriting clichés, +no generic placeholder names, no broken image links.) +``` + +## Best Practices +- **Be Descriptive:** "Deep Charcoal Ink (#18181B)" — not just "dark text" +- **Be Functional:** Explain what each element is used for +- **Be Consistent:** Same terminology throughout the document +- **Be Precise:** Include exact hex codes, rem values, pixel values in parentheses +- **Be Opinionated:** This is not a neutral template — it enforces a specific, premium aesthetic + +## Tips for Success +1. Start with the atmosphere — understand the vibe before detailing tokens +2. Look for patterns — identify consistent spacing, sizing, and styling +3. Think semantically — name colors by purpose, not just appearance +4. Consider hierarchy — document how visual weight communicates importance +5. Encode the bans — anti-patterns are as important as the rules themselves + +## Common Pitfalls to Avoid +- Using technical jargon without translation ("rounded-xl" instead of "generously rounded corners") +- Omitting hex codes or using only descriptive names +- Forgetting functional roles of design elements +- Being too vague in atmosphere descriptions +- Ignoring the anti-pattern list — these are what make the output premium +- Defaulting to generic "safe" designs instead of enforcing the curated aesthetic diff --git a/.claude/skills/design-taste-frontend b/.claude/skills/design-taste-frontend new file mode 120000 index 00000000..1e36b661 --- /dev/null +++ b/.claude/skills/design-taste-frontend @@ -0,0 +1 @@ +../../.agents/skills/design-taste-frontend \ No newline at end of file diff --git a/.claude/skills/imagegen-frontend-web b/.claude/skills/imagegen-frontend-web new file mode 120000 index 00000000..bcf2ce21 --- /dev/null +++ b/.claude/skills/imagegen-frontend-web @@ -0,0 +1 @@ +../../.agents/skills/imagegen-frontend-web \ No newline at end of file diff --git a/.claude/skills/minimalist-ui b/.claude/skills/minimalist-ui new file mode 120000 index 00000000..69c2e8c2 --- /dev/null +++ b/.claude/skills/minimalist-ui @@ -0,0 +1 @@ +../../.agents/skills/minimalist-ui \ No newline at end of file diff --git a/.claude/skills/stitch-design-taste b/.claude/skills/stitch-design-taste new file mode 120000 index 00000000..aa93660d --- /dev/null +++ b/.claude/skills/stitch-design-taste @@ -0,0 +1 @@ +../../.agents/skills/stitch-design-taste \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 52168c50..11b43777 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,7 +45,7 @@ This repo is an **MCP server** for AI agent workflow orchestration (TypeScript, # GitNexus — Code Intelligence -This project is indexed by GitNexus as **workflow-server** (9539 symbols, 12426 relationships, 213 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely. +This project is indexed by GitNexus as **workflow-server** (10264 symbols, 13634 relationships, 260 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely. > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first. diff --git a/CLAUDE.md b/CLAUDE.md index 0acc9336..9584b29e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -45,7 +45,7 @@ This repo is an **MCP server** for AI agent workflow orchestration (TypeScript, # GitNexus — Code Intelligence -This project is indexed by GitNexus as **workflow-server** (9539 symbols, 12426 relationships, 213 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely. +This project is indexed by GitNexus as **workflow-server** (10264 symbols, 13634 relationships, 260 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely. > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first. diff --git a/scripts/generate-site-data.ts b/scripts/generate-site-data.ts index 9841eadf..5cfb9c91 100644 --- a/scripts/generate-site-data.ts +++ b/scripts/generate-site-data.ts @@ -23,7 +23,7 @@ const GITHUB_BLOB = 'https://github.com/m2ux/workflow-server/blob/main'; // --------------------------------------------------------------------------- // Site route registry -export type SiteSection = 'home' | 'guide' | 'specs' | 'api' | 'internals'; +export type SiteSection = 'home' | 'guide' | 'specs' | 'api' | 'design' | 'specifications'; export interface SiteRoute { relPath: string; @@ -40,10 +40,8 @@ export interface SiteRoute { export const SITE_ROUTES: SiteRoute[] = [ { relPath: 'index.html', section: 'home', title: 'Home', navLabel: 'Home' }, { relPath: 'guide/getting-started.html', section: 'guide', title: 'Getting started', navLabel: 'Getting started', sequence: 1 }, - { relPath: 'guide/ide-setup.html', section: 'guide', title: 'IDE setup', navLabel: 'IDE setup', sequence: 2 }, - { relPath: 'guide/concepts.html', section: 'guide', title: 'Concepts', navLabel: 'Concepts', sequence: 3 }, - { relPath: 'guide/running-workflows.html', section: 'guide', title: 'Running workflows', navLabel: 'Running workflows', sequence: 4 }, - { relPath: 'guide/rationale.html', section: 'guide', title: 'Design rationale', navLabel: 'Design rationale', sequence: 5 }, + { relPath: 'guide/definitions.html', section: 'guide', title: 'Definitions', navLabel: 'Definitions', sequence: 2 }, + { relPath: 'specifications.html', section: 'specifications', title: 'Specifications', navLabel: 'Specifications', sequence: 1 }, { relPath: 'specs/architecture.html', section: 'specs', title: 'Architecture overview', navLabel: 'Overview', sequence: 0, breadcrumbLabel: 'Architecture' }, { relPath: 'specs/workflows.html', section: 'specs', title: 'Workflow architecture', navLabel: 'Workflows', sequence: 1, parent: 'specs/architecture.html', breadcrumbLabel: 'Workflows' }, { relPath: 'specs/dispatch.html', section: 'specs', title: 'Hierarchical dispatch', navLabel: 'Dispatch', sequence: 2, parent: 'specs/architecture.html', breadcrumbLabel: 'Dispatch' }, @@ -52,22 +50,33 @@ export const SITE_ROUTES: SiteRoute[] = [ { relPath: 'specs/artifact-management.html', section: 'specs', title: 'Artifact management', navLabel: 'Artifacts', sequence: 5, parent: 'specs/architecture.html', breadcrumbLabel: 'Artifacts' }, { relPath: 'specs/resource-resolution.html', section: 'specs', title: 'Resource resolution', navLabel: 'Resolution', sequence: 6, parent: 'specs/architecture.html', breadcrumbLabel: 'Resolution' }, { relPath: 'specs/workflow-fidelity.html', section: 'specs', title: 'Workflow fidelity', navLabel: 'Fidelity', sequence: 7, parent: 'specs/architecture.html', breadcrumbLabel: 'Fidelity' }, - { relPath: 'api/tools.html', section: 'api', title: 'MCP tool reference', navLabel: 'Tools', sequence: 1 }, - { relPath: 'api/schemas.html', section: 'api', title: 'Schema reference', navLabel: 'Schemas', sequence: 2 }, - { relPath: 'api/protocol.html', section: 'api', title: 'Protocol in practice', navLabel: 'Protocol guide', sequence: 3 }, - { relPath: 'internals/server-anatomy.html', section: 'internals', title: 'Server anatomy', navLabel: 'Server anatomy', sequence: 1 }, - { relPath: 'internals/request-lifecycle.html', section: 'internals', title: 'Request lifecycle', navLabel: 'Request lifecycle', sequence: 2 }, - { relPath: 'internals/session-store.html', section: 'internals', title: 'Session store', navLabel: 'Session store', sequence: 3 }, - { relPath: 'internals/quality-system.html', section: 'internals', title: 'Quality system', navLabel: 'Quality system', sequence: 4 }, + { relPath: 'api/tools.html', section: 'api', title: 'MCP tool reference', navLabel: 'API', sequence: 1 }, + { relPath: 'design/overview.html', section: 'design', title: 'Design overview', navLabel: 'Overview', sequence: 0, breadcrumbLabel: 'Design' }, + { relPath: 'design/server-anatomy.html', section: 'design', title: 'Server anatomy', navLabel: 'Server anatomy', sequence: 1, parent: 'design/overview.html', breadcrumbLabel: 'Server anatomy' }, + { relPath: 'design/request-lifecycle.html', section: 'design', title: 'Request lifecycle', navLabel: 'Request lifecycle', sequence: 2, parent: 'design/overview.html', breadcrumbLabel: 'Request lifecycle' }, + { relPath: 'design/protocol.html', section: 'design', title: 'Protocol', navLabel: 'Protocol', sequence: 3, parent: 'design/overview.html', breadcrumbLabel: 'Protocol' }, + { relPath: 'design/session-store.html', section: 'design', title: 'Session store', navLabel: 'Session store', sequence: 4, parent: 'design/overview.html', breadcrumbLabel: 'Session store' }, + { relPath: 'design/quality-system.html', section: 'design', title: 'Quality system', navLabel: 'Quality system', sequence: 5, parent: 'design/overview.html', breadcrumbLabel: 'Quality system' }, + { relPath: 'api/schemas.html', section: 'design', title: 'Schema reference', navLabel: 'Schemas', sequence: 6, parent: 'design/overview.html', breadcrumbLabel: 'Schemas' }, ]; const ROUTE_BY_PATH = new Map(SITE_ROUTES.map(r => [r.relPath, r])); -const NAV_SECTIONS: Array<{ id: SiteSection; label: string }> = [ - { id: 'guide', label: 'Guide' }, +const SECTION_LABELS: Record = { + home: 'Home', + guide: 'Guide', + specs: 'Architecture', + design: 'Design', + api: 'API', + specifications: 'Specifications', +}; + +/** Sections rendered as direct nav links before dropdowns. */ +const NAV_TOP_LEVEL_SECTIONS: SiteSection[] = ['guide', 'api']; + +const NAV_DROPDOWN_SECTIONS: Array<{ id: SiteSection; label: string }> = [ { id: 'specs', label: 'Architecture' }, - { id: 'api', label: 'API' }, - { id: 'internals', label: 'Internals' }, + { id: 'design', label: 'Design' }, ]; function routePrefix(relPath: string): string { @@ -75,6 +84,11 @@ function routePrefix(relPath: string): string { return depth === 0 ? '' : '../'.repeat(depth); } +function navScriptHref(pageRelPath: string): string { + const prefix = routePrefix(pageRelPath); + return `${prefix}nav.js`; +} + function hrefFrom(pageRelPath: string, targetRelPath: string): string { if (targetRelPath === 'index.html') { const depth = pageRelPath.split('/').length - 1; @@ -93,18 +107,22 @@ function routesInSection(section: SiteSection): SiteRoute[] { } export function renderSiteNav(pageRelPath: string): string { - const current = ROUTE_BY_PATH.get(pageRelPath); - const homeHref = hrefFrom(pageRelPath, 'index.html'); const lines: string[] = []; lines.push(' '); @@ -127,8 +151,18 @@ export function renderBreadcrumb(pageRelPath: string): string { const route = ROUTE_BY_PATH.get(pageRelPath); if (!route || route.section === 'home') return ''; + if (route.section === 'guide' || route.section === 'api' || route.section === 'specifications') { + return [ + ' ', + ].join('\n'); + } + const crumbs: Array<{ label: string; href?: string }> = []; - const sectionLabel = NAV_SECTIONS.find(s => s.id === route.section)?.label ?? route.section; + const sectionLabel = SECTION_LABELS[route.section]; const hub = routesInSection(route.section).find(r => r.sequence === 0); if (hub && route.parent === hub.relPath) { @@ -751,15 +785,24 @@ export function renderSitePages(): Array<{ relPath: string; content: string }> { content = injectRegion(content, renderPagination(relPath), 'PAGINATION'); const homeHref = hrefFrom(relPath, 'index.html'); + const siteTitle = relPath === 'index.html' + ? `Workflow Server` + : `Workflow Server`; content = content.replace( - /Workflow Server<\/a>/, - `Workflow Server`, + /Workflow Server<\/a>/, + siteTitle, ); const body = renderContentRegion(relPath); if (body !== null) { content = injectRegion(content, body, 'CONTENT'); } + + const navScript = ``; + if (!content.includes('nav.js')) { + content = content.replace('', `${navScript}\n`); + } + results.push({ relPath, content }); } return results; diff --git a/site/README.md b/site/README.md index 02c07494..05452970 100644 --- a/site/README.md +++ b/site/README.md @@ -6,7 +6,7 @@ The markdown files in the repository (`README.md`, `SETUP.md`, `docs/`, `schemas ## Navigation -Every page includes **generated global navigation** (Guide, Architecture, API, Internals, Design) produced by [`scripts/generate-site-data.ts`](../scripts/generate-site-data.ts). The route registry lives in that script as `SITE_ROUTES`. Run `npm run build:site` after adding a page or changing nav structure. +Every page includes **generated global navigation** (Guide, Architecture, Design, API) produced by [`scripts/generate-site-data.ts`](../scripts/generate-site-data.ts). The route registry lives in that script as `SITE_ROUTES`. Run `npm run build:site` after adding a page or changing nav structure. Hand-authored regions sit outside `` / `` markers. Generated regions include: @@ -21,7 +21,7 @@ Hand-authored regions sit outside `` / `
      @@ -76,7 +60,7 @@ @@ -334,8 +318,7 @@

      workflow.schema.json

      @@ -346,5 +329,6 @@

      workflow.schema.json

      + diff --git a/site/api/tools.html b/site/api/tools.html index 1effc498..d38048d6 100644 --- a/site/api/tools.html +++ b/site/api/tools.html @@ -16,19 +16,9 @@
    @@ -76,8 +60,7 @@ @@ -424,10 +407,7 @@

    get_trace

    - +
    @@ -437,5 +417,6 @@

    get_trace

    + diff --git a/site/design/overview.html b/site/design/overview.html new file mode 100644 index 00000000..b99ef70b --- /dev/null +++ b/site/design/overview.html @@ -0,0 +1,116 @@ + + + + + +Design — Workflow Server + + + + + + +
    +
    + Workflow Server + + + +
    +
    + + + + + + +
    +

    Design

    +

    The TypeScript server, the on-disk session store, the path every authenticated tool call follows, the MCP protocol on the wire, and the guards and tests that keep workflow definitions valid.

    + +
      +
    • +

      Server anatomy

      +

      Startup, tool registration, the module map, and the cross-cutting layer every handler passes through.

      + Server anatomy +
      • +
    • +

      Request lifecycle

      +

      Seven stages inside one authenticated tool call — seal verification through trace signing — using next_activity as the worked example.

      + Request lifecycle +
      • +
    • +

      Protocol

      +

      Call order, error and warning taxonomy, trace tokens, reference delivery, and dispatch on the wire.

      + Protocol +
      • +
    • +

      Session store

      +

      session.json on disk: the planning folder, derived session_index, embedded child sessions, HMAC seals, and append-only history.

      + Session store +
      • +
    • +

      Quality system

      +

      Guard scripts, Vitest suites, generated-then-guarded docs, and agent smoke runs.

      + Quality system +
      • +
    +
    + + + + + + + + + + + diff --git a/site/api/protocol.html b/site/design/protocol.html similarity index 81% rename from site/api/protocol.html rename to site/design/protocol.html index 6fa0b052..067cffba 100644 --- a/site/api/protocol.html +++ b/site/design/protocol.html @@ -3,7 +3,7 @@ -The protocol in practice — Workflow Server +Protocol — Workflow Server @@ -16,19 +16,9 @@ @@ -76,16 +60,15 @@
    -

    The protocol in practice

    -

    The tool reference gives the signatures; this page gives the conversation — what order calls must come in, what errors and warnings actually mean, how the trace works, and the delivery behaviour an agent will observe on the wire.

    -

    Prose guidance per tool is in the canonical API reference; the machinery behind each behaviour here is described in the internals section.

    +

    Protocol

    +

    The tool reference gives the signatures; this page covers call order, errors and warnings, trace tokens, reference delivery, and dispatch on the wire.

    Call order and authentication

    Three tools are callable cold — discover, list_workflows, and health_check. Everything else requires the session_index issued by start_session, and a few ordering rules carry the whole protocol:

    @@ -130,10 +113,10 @@

    Warnings: the call succeeded, and left evidence

    Your questionRead this
    I am new — where do I begin?Getting started → IDE setup → Concepts → Running workflows
    What is this project?Getting started or README (source)
    How do I install and connect the server?Getting started and SETUP (source)
    How do I wire the IDE bootstrap rule?IDE setup
    -

    Why deviations warn instead of block is a deliberate stance — see detection over prevention.

    +

    Why deviations warn instead of block follows the same rule — see the advisory layers on the fidelity page.

    The trace

    -

    Every tool call appends an event — tool, timing, outcome, workflow, activity, agent, and any validation warnings — to an in-process, per-session buffer (up to 1,000 sessions; the oldest is evicted beyond that). Each next_activity response additionally carries _meta.trace_token: the events since the previous transition, HMAC-signed into a compact token. The tokens are the durable half of the design — an orchestrator that accumulates them can hand the set to get_trace and reconstruct a tamper-evident account of the run even after the in-memory buffer is gone. Calling get_trace with no tokens returns the live buffer for the session.

    +

    Every tool call appends an event — tool, timing, outcome, workflow, activity, agent, and any validation warnings — to an in-process, per-session buffer (up to 1,000 sessions; the oldest is evicted beyond that). Each next_activity response additionally carries _meta.trace_token: the events since the previous transition, HMAC-signed into a compact token. The tokens are the durable half of the design — an orchestrator that accumulates them can hand the set to get_trace and reconstruct a tamper-evident account of the run even after the in-memory buffer is gone. Calling get_trace with no tokens returns the live buffer for the session.

    Reference delivery

    Sessions run in one of two delivery modes, recorded as contextMode. In fresh mode (the default) every fetch returns full content — right for disposable workers that start with empty context. In persistent mode the server keeps a per-agent ledger of content hashes and replaces anything already delivered with a short marker:

    @@ -181,17 +164,18 @@

    Dispatch in practice

    • get_workflow_status is the orchestrator's poll — position, active checkpoint, and child statuses without touching execution.
    • A child reaching its terminal activity flips its entry in the parent's triggeredWorkflows to completed; the parent discovers this on its next status read rather than by callback.
      • -
    • Because children are embedded, not separate files, resuming the parent by folder name resumes the entire tree.
      • +
    • Because children are embedded, not separate files, resuming the parent by folder name resumes the entire tree.

    Next

    -

    Signatures for every tool are on the tool reference; the server-side mechanics of a call are in the request lifecycle.

    +

    Signatures for every tool are on the tool reference; server-side mechanics are in request lifecycle.

    @@ -202,5 +186,6 @@

    Next

    + diff --git a/site/internals/quality-system.html b/site/design/quality-system.html similarity index 90% rename from site/internals/quality-system.html rename to site/design/quality-system.html index 5d1d3047..de726158 100644 --- a/site/internals/quality-system.html +++ b/site/design/quality-system.html @@ -16,19 +16,9 @@ @@ -76,7 +60,7 @@ @@ -84,7 +68,7 @@

    Quality system

    -

    Executable guards encode conventions that matter: reference integrity, naming rules, schema truthfulness, and site link integrity.

    +

    Executable guards encode conventions that matter: reference integrity, naming rules, schema truthfulness, and site link integrity. Recurring authoring mistakes become named anti-patterns, mechanical guards, and baselines that ratchet toward zero.

    For contributors. Guards live in scripts/ as npm run check:*; tests run under Vitest in tests/.

    The guard suite

    @@ -118,7 +102,7 @@

    The test architecture

    Generated, then guarded

    -

    Two artifacts are machine-derived from the source, and both are guarded against drift rather than trusted to stay fresh:

    +

    Two artifacts are machine-derived from the source, and both are guarded against drift rather than trusted to stay fresh. The documentation site itself follows the same pattern — hand-authored pages with generated API regions — and check-site-links / check-svg-layout keep links and diagrams honest:

    @@ -170,13 +154,14 @@

    Generated, then guarded

    The same discipline extends to deployment: the GitHub Pages workflow re-runs the site guards before publishing, so the deployed site is exactly the checked, committed one.

    Next

    -

    Why the project invests in mechanical guardrails rather than review vigilance is part of the design rationale; the runtime half of the same philosophy is workflow fidelity.

    +

    Where this machinery lives in the server is server anatomy; how runs are kept on-script at runtime is workflow fidelity.

    @@ -187,5 +172,6 @@

    Next

    + diff --git a/site/internals/request-lifecycle.html b/site/design/request-lifecycle.html similarity index 90% rename from site/internals/request-lifecycle.html rename to site/design/request-lifecycle.html index efdc1a48..44be27d1 100644 --- a/site/internals/request-lifecycle.html +++ b/site/design/request-lifecycle.html @@ -16,19 +16,9 @@ @@ -76,7 +60,7 @@ @@ -84,7 +68,7 @@

    Request lifecycle

    -

    Every authenticated tool call follows the same skeleton: verify the session, load the definition, validate the claim the agent is making, advance the state, reseal it, and sign the trace. This page walks that skeleton using next_activity — the most eventful call — as the example.

    +

    Every authenticated tool call follows the same skeleton: verify the session, load the definition, validate the claim the agent is making, advance the state, reseal it, and sign the trace. That uniformity is possible because the whole system crosses one boundary — sixteen MCP tools with schema-validated parameters, no side channel, no shared files as API. This page walks that skeleton using next_activity — the most eventful call — as the example.

    The handlers live in src/tools/workflow-tools.ts; the shared machinery each stage uses is mapped in server anatomy.

    @@ -155,7 +139,7 @@

    4. Fidelity checks

    -

    The split is deliberate: only checks that are cheap and certain block the call; everything judgment-shaped becomes a warning in the response and the trace. Detection over prevention explains why.

    +

    The split is deliberate: only checks that are cheap and certain block the call; everything judgment-shaped becomes a warning in the response and the trace — see the advisory layers on the fidelity page.

    5. Advancing the state

    advanceSession applies the mutation as a controlled update: the monotonic seq counter increments, the timestamp refreshes, and the handler's mutator appends history events — activity_exited for the activity being left, activity_entered for the new one, and workflow_completed when the transition is terminal. A child session reaching its terminal state also notifies its parent, flipping the child's entry in the parent's triggeredWorkflows to completed (best-effort — a moved parent is tolerated).

    @@ -165,7 +149,7 @@

    6. Persisting and resealing

    7. Signing the trace and responding

    When tracing is enabled, the events accumulated since the last next_activity are packaged into a trace-token payload, HMAC-signed, and returned in _meta.trace_token — a tamper-evident receipt for that leg of the run, reconstructable later via get_trace.

    -

    The response body itself stays minimal: next_activity returns just the new activity's id and name, because the full definition is the worker's to fetch via get_activity. Alongside it, _meta.validation carries the outcome of stage four — { status, warnings } — so deviations are visible to the orchestrator on the very call that detected them. The warning taxonomy, error surfaces, and delivery markers an agent may encounter are catalogued in the protocol in practice.

    +

    The response body itself stays minimal: next_activity returns just the new activity's id and name, because the full definition is the worker's to fetch via get_activity. Alongside it, _meta.validation carries the outcome of stage four — { status, warnings } — so deviations are visible to the orchestrator on the very call that detected them. The warning taxonomy, error surfaces, and delivery markers an agent may encounter are catalogued in Protocol.

    Next

    The state this lifecycle protects is described field-by-field in the session store; the checks that guard the definitions themselves are in the quality system.

    @@ -175,7 +159,7 @@

    Next

    @@ -186,5 +170,6 @@

    Next

    + diff --git a/site/internals/server-anatomy.html b/site/design/server-anatomy.html similarity index 81% rename from site/internals/server-anatomy.html rename to site/design/server-anatomy.html index 30c3ed01..e8430da3 100644 --- a/site/internals/server-anatomy.html +++ b/site/design/server-anatomy.html @@ -16,19 +16,9 @@ @@ -76,7 +60,7 @@ @@ -84,7 +68,7 @@

    Server anatomy

    -

    The architecture models describe guarantees; this page maps them to code in src/.

    +

    The workflow-server codebase in src/: entry point, tool registrars, loaders, session machinery, and validators.

    For contributors. Build and test instructions: Development guide (source).

    The shape of the codebase

    @@ -168,11 +152,11 @@

    Persistence and delivery

    The layer every call passes through

    -

    Three functions form a choke point that every authenticated tool call traverses, which is what makes the server's observability and integrity guarantees uniform rather than per-tool:

    +

    There is no central router — each tool is a closure registered at startup — but session-bound handlers follow the same skeleton so logging, seal checks, and persistence are uniform. Every handler is wrapped in withAuditLog. Tools that take a session_index call loadSessionForTool before touching state and saveSessionForTool after any mutation. Bootstrap entry points — discover, list_workflows, health_check, and start_session — get audit logging only. The worked example is request lifecycle.

      -
    1. withAuditLog (logging.ts) wraps each handler — it times the call, emits a structured audit event to stderr, and appends a trace event to the session's TraceStore buffer.
      2. -
    2. loadSessionForTool (session/resolver.ts) resolves the session_index to a planning folder, verifies the HMAC seal, and validates session.json against the session schema before the handler sees any state.
      3. -
    3. saveSessionForTool persists the updated state atomically and recomputes the seal, so no code path can write state without resealing it.
      4. +
    4. withAuditLog (logging.ts) — outermost wrapper on every registered handler. It times the call, emits a structured audit event to stderr, and — when the parameters include a session_index — appends a trace event to the session's in-process TraceStore buffer. This runs on success and on thrown errors alike, so a failed seal check or validation still leaves an audit and trace record.
      5. +
    5. loadSessionForTool (session/resolver.ts) — resolves the six-character session_index to a planning folder (how the index maps to disk), verifies the HMAC seal on session.json against .session-token, and parses the file into typed SessionFile state. Child sessions dispatched via dispatch_child live inside the parent's session.json; the loader navigates to the embedded sub-state the index addresses. If the seal does not match or the file fails schema validation, the call stops here — the handler never runs on state the server cannot vouch for.
      6. +
    6. advanceSession and saveSessionForTool (session/resolver.ts) — the write path. Handlers that change state build the next snapshot with advanceSession (increments seq, refreshes ts, applies a mutator callback), then pass it to saveSessionForTool, which merges embedded child updates back into the top-level file, canonicalises the JSON, recomputes the HMAC, and atomically writes session.json and .session-token. Read-only tools such as get_activity may still call save when they record delivery or fetch events in history.

    Everything cryptographic — session seals, session indexes, trace tokens — funnels to a single 32-byte server key created lazily at ~/.workflow-server/secret (file mode 0600) by session/crypto.ts. One key, three uses, one place to reason about it.

    @@ -191,11 +175,11 @@

    Error discipline

    -

    How these surface to a calling agent — and how they differ from non-blocking validation warnings — is covered in the protocol in practice.

    +

    How these surface to a calling agent — and how they differ from non-blocking validation warnings — is covered in Protocol.

    Where things live on disk

      -
    • Workflow definitions are read from the configured workflow directory — in this repository, the workflows/ worktree of the orphan workflows branch (why an orphan branch).
      • +
    • Workflow definitions are read from the configured workflow directory — in this repository, the workflows/ worktree of the orphan workflows branch (why an orphan branch).
    • Session state is written under <workspace>/.engineering/artifacts/planning/<slug>/ — the session store page covers the folder's contents.
    • The server key lives at ~/.workflow-server/secret, per user, outside any repository.
    @@ -219,5 +203,6 @@

    Next

    + diff --git a/site/internals/session-store.html b/site/design/session-store.html similarity index 90% rename from site/internals/session-store.html rename to site/design/session-store.html index e37fafc1..3914dfa6 100644 --- a/site/internals/session-store.html +++ b/site/design/session-store.html @@ -16,19 +16,9 @@ @@ -76,7 +60,7 @@ @@ -84,8 +68,8 @@

    Session store

    -

    A session is a folder. Everything the server knows about a run — position, variables, history, children — lives in one sealed session.json inside a planning folder in your workspace, and every piece of the design follows from making that file trustworthy, resumable, and inspectable.

    -

    The implementation is src/utils/session/; the file's exact shape is session-file.schema.json, and the user-level view of the same folder is in artifact and workspace isolation.

    +

    A session is a folder. Everything the server knows about a run — position, variables, history, children — lives in one sealed session.json inside a planning folder in your workspace. Agents identify a run with a derived six-character session_index, not a path or hand-carried token; the server holds the truth. Every piece of the design follows from making that file trustworthy, resumable, and inspectable.

    +

    The implementation is src/utils/session/; the file's exact shape is session-file.schema.json, and the user-level view of the same folder is in artifact and workspace isolation. The server needs a workspace at launch, and every authenticated call reads or writes disk.

    @@ -144,7 +128,7 @@

    What the file records

    PositioncurrentActivity, completedActivities, skippedActivities, status (running, completed, aborted), and activeCheckpoint — the gate that pauses navigation while a decision is outstanding. Datavariables, the schema-validated bag mutated only through declared paths (checkpoint effects and recorded outputs — see state management), plus checkpointResponses, which caches each resolved checkpoint so a replayed yield returns the earlier answer instead of asking twice. Orderingseq, a monotonic counter bumped by every mutation, and ts — together they make "which write is newer" a comparison, not a guess. - DeliverycontextMode (persistent or fresh) and deliveredContent, the per-agent ledger of content hashes behind reference-not-repeat delivery. + DeliverycontextMode (persistent or fresh) and deliveredContent, the per-agent ledger of content hashes behind reference-not-repeat delivery. StructuretriggeredWorkflows (embedded child sessions), parentSession (the back-reference), and planningFolderPath, re-stamped on resume so the file stays correct if the folder moves. HistoryThe append-only event log described next. @@ -160,7 +144,7 @@

    Nested and transient sessions

    Meta-orchestration sessions that exist only to choose a workflow start transient — created under the system temporary directory with a synthetic slug. The first dispatch_child that commits to real work promotes the session into the workspace planning root, taking its slug from the request (or a dated fallback), and the temporary folder is discarded. Nothing about a browse-only conversation ever lands in your repository.

    Integrity and migration

    -

    The seal answers one question: is this file exactly what the server last wrote? Writes are atomic (temp file, then rename), the HMAC is computed over canonicalized JSON, and reads verify it with a timing-safe comparison before parsing. What it defends against is corruption, manual edits, restored backups, and racing writers — incoherence, not adversaries; the threat model is spelled out in the rationale.

    +

    The seal answers one question: is this file exactly what the server last wrote? Writes are atomic (temp file, then rename), the HMAC is computed over canonicalized JSON, and reads verify it with a timing-safe comparison before parsing. The goal is catching corruption, hand-edits, restored backups, and racing writers — incoherence, not an adversary-proof security boundary. One server key, cheap digests, hard failure on mismatch.

    Older planning folders that predate the current layout are upgraded in place by migration.ts the first time they are touched; an upgrade that cannot complete raises MigrationError rather than leaving a half-converted folder.

    Next

    @@ -170,7 +154,7 @@

    Next

    @@ -182,5 +166,6 @@

    Next

    + diff --git a/site/guide/concepts.html b/site/guide/concepts.html deleted file mode 100644 index add4e739..00000000 --- a/site/guide/concepts.html +++ /dev/null @@ -1,197 +0,0 @@ - - - - - -Concepts — Workflow Server - - - - - - -
    -
    - Workflow Server - - - -
    -
    - - - - - - -
    -

    Concepts

    -

    Five ideas explain the system: workflows, activities, techniques, sessions, and checkpoints. The model diagram on the home page shows how they chain from a user goal down to tool calls. For file layout, step kinds, and binding, see Workflows under Architecture.

    - -

    Terms at a glance

    -
    - - - - - - - - - -
    TermPlain meaning
    Work packageA bundled workflow for planning and implementing one unit of work (for example a feature or issue). You start or resume it in natural language.
    MCPModel Context Protocol. How your IDE talks to the workflow-server process.
    SessionOne run of a workflow. State lives in your project's .engineering/artifacts/planning/ folder.
    CheckpointA deliberate pause where you approve, choose, or confirm before work continues.
    TechniqueA markdown document describing how to perform one capability.
    -
    - -

    What a workflow is made of

    -

    A workflow is a directory of declarative files — manifest, activities, techniques, and resources — not executable code. Workflows walks through each piece with diagrams: what lives on disk, the four step kinds, how techniques compose, and what the server delivers at runtime.

    - -

    Sessions

    -

    A session is one run of a workflow. When the agent calls start_session, the server creates (or resumes) a planning folder under your project's .engineering/artifacts/planning/ and writes a session.json there — the canonical record of which activity is current, which variables are set, and whether a checkpoint is active. The tool returns a short session_index token that identifies the session on every later call.

    -

    Because the state lives on disk in your project, sessions survive restarts: asking the agent to resume a work package finds the planning folder by name and picks up exactly where it stopped.

    - -

    Checkpoints — where you stay in control

    -

    A checkpoint is a step where the workflow deliberately stops until you decide something: approve a design, pick an option, confirm a commit. The agent cannot skip past one — the server records the active checkpoint in the session state and refuses to advance until it is resolved.

    - -
    - - The checkpoint flow - A sequence with three participants: you, the agent, and the server. The agent reaches a checkpoint step and calls yield underscore checkpoint; the server records it. The agent calls present underscore checkpoint and receives the message and options, presents the decision to you, and you choose. The agent submits your choice with respond underscore checkpoint, then calls resume underscore checkpoint and continues working with any variable updates. - - - - - - - - You - - Agent - - Server - - - - - - - - - - - - - - - - - yield_checkpoint - checkpoint recorded, work pauses - present_checkpoint - message + options - presents the decision to you - your choice - respond_checkpoint → resume_checkpoint - - work continues with any variable updates from your choice - -
    The checkpoint flow, simplified to a single agent. The agent yields at the checkpoint, fetches the message and options, presents the decision to you, submits your choice, and resumes. In multi-agent setups the yield "bubbles up" from a background worker to the user-facing agent — the full protocol is in the checkpoint model.
    -
    - -

    Your choice can set workflow variables — picking "skip the audit" or "include migration" changes which activities and steps run afterwards. Some checkpoints define a default option and can auto-advance after a timeout; the server still enforces the timer.

    - -

    Techniques and resources

    -

    A technique is a markdown document that tells the agent how to perform one capability. At runtime:

    -
      -
    • activity steps bind techniques by reference
      • -
    • the agent fetches each one just-in-time with get_technique as it reaches the step
      • -
    • resources load with get_resource only when a technique links to one
      • -
    -

    On-disk layout: Workflows. Path resolution, composition, and lazy loading: Resolution. Techniques differ from conventional agent skills (description-triggered instruction packages) — see Design rationale → Why techniques, not skills?.

    - -

    Fidelity: why agents stay on script

    -

    The server enforces the workflow instead of trusting the agent to follow it:

    -
      -
    • transitions are validated
      • -
    • checkpoints gate advancement
      • -
    • session state on disk is the single source of truth
      • -
    -

    Read workflow fidelity for what each layer protects against, and architecture overview for the six models behind it.

    - -

    Next

    -

    Workflows — file layout, step kinds, binding, and runtime delivery. Then run your first workflow.

    -
    - - - - - - - - - - diff --git a/site/guide/definitions.html b/site/guide/definitions.html new file mode 100644 index 00000000..4bc5c2b0 --- /dev/null +++ b/site/guide/definitions.html @@ -0,0 +1,212 @@ + + + + + +Definitions — Workflow Server + + + + + + +
    +
    + Workflow Server + + + +
    +
    + + + + + + +
    +

    Definitions

    +

    Plain-language definitions for terms you will see across the docs, the site, and your agent's workflow runs. The model diagram on the home page shows how the core pieces chain from a user goal down to tool calls. For file layout, step kinds, and runtime delivery, see Workflows; for checkpoint mechanics, see Checkpoints.

    + +

    Terms

    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    TermIn brief
    ActionInline step instructions the agent executes directly
    ActivityA phase of a workflow — plan, implement, review
    ArtifactA planning output written under your session folder
    Bootstrap ruleIDE rule that makes the agent call discover first
    CheckpointA deliberate pause for your decision
    DiscoverBootstrap tool that returns the startup procedure
    DispatchHow orchestrators spawn and coordinate workers
    FidelityServer enforcement that keeps agents on the defined path
    GoalWhat you ask for in natural language
    LoopA step that repeats nested steps until a condition clears
    ManifestThe workflow.yaml file that defines a workflow
    MCPHow your IDE talks to the workflow-server process
    OrchestratorAgent that manages workflow state and user interaction
    Planning folderPer-session directory under .engineering/artifacts/planning/
    ResourceReference material a technique can link to
    RuleBehaviour constraint applied across a workflow or activity
    SessionOne run of a workflow, persisted on disk
    Session indexShort token that identifies a session on every tool call
    StepOne ordered unit of work inside an activity
    TechniqueMarkdown definition of one capability
    ToolAn MCP operation the agent invokes through the server
    TransitionRule for which activity runs next
    VariableNamed value in session state that steps read and write
    Work packageThe bundled workflow for one unit of work
    WorkerBackground agent that executes activity steps
    WorkflowThe overall process from start to finish
    Workflow serverThe MCP server that enforces workflows and owns session state
    WorkspaceYour project root the server manages sessions for
    +
    + +

    Action

    +

    An action is a step kind with inline instructions — validate something, emit a message, set a flag — rather than delegating to a technique file. The agent executes the listed actions against current variables; the server records progress but does not interpret the action verbs themselves. See step kinds.

    + +

    Activity

    +

    An activity is one phase of a workflow: planning, implementation, review, validation, and so on. Each activity is a YAML file listing ordered steps and optional transitions to other activities. The orchestrator moves between activities as the run progresses; the server tracks which activity is current in session.json. See Activities.

    + +

    Artifact

    +

    An artifact is a planning output the workflow stores in your session folder — design notes, compliance reviews, implementation plans — separate from your application source code. Artifacts give later activities and checkpoints something concrete to reference. See Artifacts.

    + +

    Bootstrap rule

    +

    The bootstrap rule is a short always-applied instruction in your IDE that routes workflow requests through discover before any other workflow-server tool. Without it, agents may skip the startup sequence and call tools out of order. Add it during setup — see Getting started.

    + +

    Checkpoint

    +

    A checkpoint is a deliberate pause where the workflow stops until you approve, choose, or confirm something. The server records an active checkpoint in session state and refuses to advance until it is resolved; your choice can also set variables that change what runs next. See Checkpoints.

    + +

    Discover

    +

    Discover is the bootstrap MCP tool that returns the ordered startup procedure — which tools to call, in what sequence — for starting or resuming a workflow. Agents should call it on every workflow request when the bootstrap rule is in place. See Tool reference.

    + +

    Dispatch

    +

    Dispatch is how the server hands work to the right agent layer: a user-facing orchestrator manages state and checkpoints, while ephemeral workers execute activity steps in the background and bubble pauses back up when they need your input. See Dispatch.

    + +

    Fidelity

    +

    Fidelity is the server's job of enforcing the workflow definition instead of trusting the agent to follow it voluntarily — validating transitions, gating advancement at checkpoints, and keeping session state on disk as the single source of truth. See Fidelity.

    + +

    Goal

    +

    A goal is what you state in natural language — implement issue #42, start a work package for authentication — and the agent matches to a workflow. You never name tools or session tokens; the server and bootstrap procedure handle routing once the goal is understood.

    + +

    Loop

    +

    A loop is a step kind that repeats a nested list of steps until a condition is satisfied or the loop declares completion. Loops let activities revisit work — retry a validation, iterate on a plan — without duplicating step definitions. See step kinds.

    + +

    Manifest

    +

    The manifest is the workflow.yaml file at the root of a workflow directory. It declares the workflow's identity, variables, activity list, initial activity, and orchestrator-level techniques and rules — the map the server reads when a session starts. See Workflows.

    + +

    MCP

    +

    MCP (Model Context Protocol) is the wire format your IDE uses to talk to external tools. The workflow-server registers as an MCP server; your agent calls its tools through the client's MCP configuration. See modelcontextprotocol.io and Getting started.

    + +

    Orchestrator

    +

    An orchestrator is the agent layer that owns workflow navigation — calling next_activity, presenting checkpoints to you, and spawning workers for individual activities. In a typical run you interact with the top-level orchestrator; background workers stay out of your chat. See Dispatch.

    + +

    Planning folder

    +

    A planning folder is the per-session directory under .engineering/artifacts/planning/ where the server writes session.json, artifacts, and traces. Because state lives in your project tree, sessions survive IDE restarts and can be resumed by name across conversations.

    + +

    Resource

    +

    A resource is reference material — extra markdown the server can attach when a technique links to it. Resources load lazily with get_resource only when needed, so the agent's context stays focused on the step in front of it. See Resources and Resolution.

    + +

    Rule

    +

    A rule is a behaviour constraint declared in workflow or activity YAML — conduct the agent must follow across a whole run or a single phase. Rules complement techniques: techniques describe how to do one capability; rules set boundaries that apply while those techniques run. See Workflows.

    + +

    Session

    +

    A session is one run of a workflow from start to completion (or pause). The server creates or resumes a planning folder, writes canonical state to session.json, and returns a session index token for every subsequent tool call. Ask the agent to resume a work package and it picks up from the saved state.

    + +

    Session index

    +

    The session index is the short token returned by start_session that identifies which planning folder a tool call belongs to. Agents pass it on later workflow-server calls so the server can load the right session.json without you copying paths or IDs. See start_session.

    + +

    Step

    +

    A step is one ordered unit of work inside an activity. Steps run in file order unless a loop or transition sends execution elsewhere; each step has a kind — technique, action, checkpoint, or loop — that tells the agent what to do. See step kinds.

    + +

    Technique

    +

    A technique is a markdown file that defines one capability: what it does, what inputs it needs, what outputs it produces, and the protocol steps to follow. Activity steps bind techniques by :: path; the agent fetches each one just-in-time with get_technique rather than reading repository files directly. See Techniques.

    + +

    Tool

    +

    A tool is an MCP operation exposed by the workflow-server — discover, start_session, get_activity, yield_checkpoint, and others. The agent invokes tools; the server validates each call against the workflow definition and updates session state. You do not call these yourself. See Tool reference.

    + +

    Transition

    +

    A transition is a rule that decides which activity runs next when the current one finishes. Transitions read variables and checkpoint outcomes from session state; the server evaluates them deterministically rather than letting the agent guess. See State.

    + +

    Variable

    +

    A variable is a named slot in session state — target_path, issue_number, flags set by checkpoint choices — that steps and transitions read and write. The manifest seeds defaults at session start; techniques and checkpoints update the bag as the run proceeds. See Variables and binding.

    + +

    Work package

    +

    A work package is the bundled work-package workflow for planning and implementing one unit of work — a feature, an issue, a remediation. You start or resume it in natural language; the server handles session creation, activity navigation, and checkpoints along the way. See Run and resume.

    + +

    Worker

    +

    A worker is a background agent spawned to execute the steps inside one activity. Workers call techniques and yield checkpoints; they do not prompt you directly — pauses bubble up to the orchestrator that faces you. See Dispatch.

    + +

    Workflow

    +

    A workflow is the whole process from start to finish — a directory of declarative YAML and markdown files, not executable code. It lists activities, variables, techniques, and rules; the server reads the manifest and enforces the path the agent follows. See Workflows.

    + +

    Workflow server

    +

    The workflow server is the MCP server in this repository. It loads workflow definitions from the workflows/ worktree, exposes tools for agents to navigate them, enforces fidelity and checkpoints, and persists session state in your project's workspace. See Home and Getting started.

    + +

    Workspace

    +

    The workspace is your project root — the repository the server manages sessions for, set via WORKFLOW_WORKSPACE or --workspace. Session folders and artifacts live under its .engineering/ tree; the server refuses to start without a workspace path. See Configure your MCP client.

    + +

    Next

    +

    Workflows — file layout, step kinds, binding, and runtime delivery. Architecture overview — the enforcement models behind the server.

    +
    + + + + + + + + + + + diff --git a/site/guide/getting-started.html b/site/guide/getting-started.html index c0ccc203..606d0c3c 100644 --- a/site/guide/getting-started.html +++ b/site/guide/getting-started.html @@ -4,7 +4,7 @@ Getting started — Workflow Server - + @@ -16,19 +16,9 @@ @@ -76,7 +60,6 @@ @@ -84,47 +67,7 @@

    Getting started

    -

    Install the server, connect your MCP client, and verify the agent can list workflows. You need Node.js 18+ and an MCP client (Cursor, Claude Desktop, Claude Code, or similar).

    - -

    The pieces

    -

    Three parts work together: your MCP client, the workflow-server process, and your project's planning workspace.

    - -
    - - Deployment topology - Your MCP client communicates with the workflow-server process over MCP. The server reads workflow definitions from the workflows directory and reads and writes session state under your project's engineering planning folder. - - - - - - - - MCP client - Cursor · Claude Desktop · … - - workflow-server - Node.js process - - Workflow definitions - WORKFLOW_DIR (read) - - Your project - session state (read/write) - - - - - - - - MCP (stdio) - reads - reads / writes - - -
    The MCP client launches and talks to the workflow-server over stdio. The server reads workflow definitions from WORKFLOW_DIR and keeps session state under your project's .engineering/artifacts/planning/ folder (the workspace).
    -
    +

    Install the server, connect your MCP client, add the bootstrap rule, and run workflows in natural language. You need Node.js 18+ and an MCP client (Cursor, Claude Desktop, Claude Code, or similar). For how the client, server, and workspace fit together, see The pieces on the home page.

    1. Install and build

    # Clone and install
@@ -137,7 +80,7 @@ 
    1. Install and build
    
 
 # Build the server
 npm run build
    -

    The workflow definitions live on a separate workflows branch, checked out as a worktree (a second folder from the same repo). Server code and workflow data can evolve independently.

    +

    The workflow definitions live on a separate workflows branch — an orphan branch with no shared history with main — checked out as a worktree beside the server code. Server releases and workflow edits change on different cadences; separate histories let you pin each side independently and keep content pull requests out of server review.

    @@ -195,7 +155,7 @@

    Next steps

    @@ -205,5 +165,6 @@

    Next steps

    + diff --git a/site/guide/ide-setup.html b/site/guide/ide-setup.html deleted file mode 100644 index 74031382..00000000 --- a/site/guide/ide-setup.html +++ /dev/null @@ -1,127 +0,0 @@ - - - - - -IDE setup — Workflow Server - - - - - - -
    -
    - Workflow Server - - - -
    -
    - - - - - - -
    -

    IDE setup

    -

    One always-applied rule connects your IDE agent to the server. It does not encode the full protocol; it makes the agent call discover first, and the server returns the current bootstrap procedure.

    - -

    The bootstrap rule

    -

    Add this to your IDE's "always-applied" rule set (a Cursor rule, a Claude Code project rule, or the equivalent in your client):

    - 
    For any start workflow, create work package, or resume work package request, call the `discover` tool on the workflow-server MCP server to learn the bootstrap procedure. Complete the procedure before any other action.
-
-If the user provides a `session_token`, pass it to subsequent workflow-server calls per their instructions.
    -

    The rule wires natural-language requests ("start a work package", "resume the workflow") into the server's bootstrap procedure. Because the agent always asks the server first, the procedure stays in sync with the running server version.

    - -

    What discover returns

    -
      -
    • Server name and version — confirms which workflow server the agent is talking to.
      • -
    • The bootstrap procedure — the canonical tool-calling sequence (list_workflows → start_session → get_workflow → next_activity → get_activity), with checkpoint discipline layered in.
      • -
    • Available workflows — IDs, titles, and tags the agent matches your request against.
      • -
    - -

    Schema awareness (optional)

    -

    The server exposes its JSON Schemas via the MCP resource workflow-server://schemas. Agents that author or validate workflow definitions can fetch it on startup — the same schemas are browsable in the schema reference.

    - -

    Verifying the connection

    -

    After restarting your MCP client, confirm the basic connection in Getting started → Verify (list workflows).

    -

    Then test the IDE rule — ask the agent to start a work-package workflow. It should call discover first, then proceed through list_workflows, start_session, and get_workflow.

    -

    If the agent skips discover, the rule has not been picked up — re-check your IDE's rule configuration.

    -
    - - - - - - - - - - diff --git a/site/guide/rationale.html b/site/guide/rationale.html deleted file mode 100644 index 4608f976..00000000 --- a/site/guide/rationale.html +++ /dev/null @@ -1,170 +0,0 @@ - - - - - -Design rationale — Workflow Server - - - - - - -
    -
    - Workflow Server - - - -
    -
    - - - - - - -
    -

    Design rationale

    -

    The specifications describe what the system does. This page explains why it is shaped that way.

    -

    For contributors and architects. If you only need to run workflows, start with the user guide.

    - -

    Who holds the truth

    - -

    The server owns the state, not the agent

    -

    Session truth lives in a sealed session.json on disk; agents hold only a short index.

    -

    Earlier designs had agents transcribe opaque tokens between calls. Tokens drifted, truncated, or were reconstructed from memory. ADR-0003 moved the record to server-managed session state. Cost: the server needs a workspace at launch, and every authenticated call reads or writes disk.

    - -

    Integrity, not security

    -

    HMAC seals detect corruption and incoherence; they are not an adversary-proof security boundary.

    -

    The seals catch corrupted files, hand-edits, restored backups, and racing writers. One server key, cheap digests, hard failure on mismatch.

    - -

    Determinism over model judgment

    -

    Resolve plumbing mechanically; reserve model judgment for the actual work.

    -

    Transitions, artifact contracts, binding provenance, and delivery payloads are computed from definitions and state. Same inputs, same path.

    - -

    How agents experience the system

    - -

    One narrow surface: MCP tools

    -

    Everything crosses a single boundary — sixteen MCP tools with schema-validated parameters. No side channel, no shared files as API, no prompt-injection-by-convention. A narrow, typed surface is what makes the uniform lifecycle possible: because every interaction is a tool call, every interaction can be authenticated, validated, traced, and audited by the same three functions. It also keeps the server client-agnostic: anything that speaks MCP gets the full system.

    - -

    Progressive disclosure: context is the scarce resource

    -

    An agent's context window is the system's real budget constraint, and the delivery design treats it that way. Definitions arrive at the granularity of need: workflow metadata at get_workflow, one activity at a time at get_activity, one technique per step at get_technique, resources only when a technique actually cites them. Two refinements came from watching real runs. Reference-not-repeat delivery replaces already-delivered content with unchanged hash markers for persistent-context agents, because re-sending identical bundles was the single largest token waste. And fetch recording makes laziness observable — since the server cannot force an agent to read, it records what was fetched and warns when a manifested step was never loaded, converting silent corner-cutting into a visible signal.

    - -

    Checkpoints yield first, present later

    -

    A checkpoint's pause and its presentation are different concerns with different owners. The worker that hits a checkpoint records the pause (yield_checkpoint) and steps aside; the user-facing agent later loads the decision (present_checkpoint) and submits the answer (respond_checkpoint). Splitting the two lets a pause bubble up through any number of dispatch layers while the server enforces the invariant that matters — nothing advances past an unresolved checkpoint, wherever it was raised. The minimum-response-time check exists for the same reason the gate does: a checkpoint answered in under three seconds was answered by a model, not a person.

    - -

    Three layers of dispatch

    -

    The meta orchestrator, workflow orchestrator, and activity workers (the dispatch model) are separated by what they must not share: user conversation, workflow state, and task context. Fresh workers per activity keep each execution's context clean and disposable; the embedded child-session design keeps the whole work package in one resumable file despite the layering. The design deliberately tolerates hosts without sub-agent support — dispatch degrades to inline execution — because portability across MCP clients mattered more than mandating an execution topology.

    - -

    How behaviour is defined

    - -

    Techniques are markdown with a contract

    -

    Structured capabilities the server can compose, bind, and deliver — not ambient skill prompts.

    -

    Process knowledge is written in markdown with declared inputs, outputs, an ordered protocol, and optional rules — parseable enough for the server to compose, validate, and bind them; readable enough for a human to review in a pull request and an agent to follow verbatim. The alternative poles were both rejected: free-form prose cannot be checked, and a rigid programmatic format cannot hold the judgment-laden guidance that makes techniques worth having.

    - -

    Why techniques, not skills?

    -

    Agent platforms popularised skills — markdown packages with a short description and instructions the model loads when a request seems to match. That shape works well for ambient, opt-in guidance. This server orchestrates multi-step workflows where an activity step names a capability, the server binds it to session variables, and fidelity depends on knowing exactly what was delivered.

    -
      -
    • Formal sections — Capability, Inputs, Outputs, Protocol, and Rules are canonical and schema-checked (schema reference), so the server can merge ancestor contracts, wrap protocols with container Initial/Final blocks, and flag definition defects — not merely paste prose into context.
      • -
    • Granular composition — nested :: paths, grouped folders, and per-activity techniques[] lists let one activity assemble exactly the capabilities it needs (Resolution).
      • -
    • Precision delivery — the server delivers workflow metadata, then one activity, then step techniques and resources on demand (progressive disclosure), with bundling budgets and fetch recording — not whole skill files chosen by trigger matching.
      • -
    • Protocol vs reference — the protocol states imperative steps to execute; bulky templates, checklists, and API guides live in resources/ and load via get_resource only when a running technique links to them (Workflows → Resources). Skills conventionally mix procedure and reference in one package; here the split is structural.
      • -
    -

    The contract layer — typed identifiers, binding provenance, inheritance — exists where orchestration needs mechanical guarantees, not model discretion. See Workflows for on-disk layout and technique protocol (source) for the normative file shape.

    - -

    Workflow data on an orphan branch

    -

    Workflow definitions live on a workflows branch with no shared history with main, checked out as a worktree. The two bodies change for different reasons on different cadences: server releases are code events; workflow edits are content events, often several per day while a process is being tuned. Separate histories mean content changes never entangle server review, a deployment can pin either side independently, and the same server can mount a different corpus per project. The cost is a two-step setup (git worktree add) and the standing rule that content PRs and server PRs stay separate.

    - -

    How the project keeps itself honest

    - -

    Detection over prevention

    -

    Only cheap-and-certain checks block; interpretive ones warn.

    -

    Of the seven fidelity layers, seal verification and the checkpoint gate hard-block. Manifest completeness, version drift, and fetch coverage surface warnings in _meta and the trace instead. See workflow fidelity for what each layer does and its honest limitations.

    - -

    Guards, anti-patterns, baselines

    -

    Turn recurring authoring mistakes into mechanical checks.

    -

    Named anti-patterns, guards, and baselines ratchet violations toward zero — see the quality system. In a YAML-and-markdown codebase, convention enforcement cannot live in reviewer vigilance alone.

    - -

    A hand-authored documentation site

    -

    Plain HTML with generated pages where the code is the source of truth.

    -

    This site replaced a static-site-generator pipeline with hand-authored pages, one stylesheet, and inline SVG. API and schema pages are generated and drift-tested; link and diagram integrity ride the same guard suite as everything else.

    - -

    Next

    -

    See these decisions as running code in the internals section, or as guarantees in the architecture models.

    -
    - - - - - - - - - - diff --git a/site/guide/running-workflows.html b/site/guide/running-workflows.html deleted file mode 100644 index 21bcaf78..00000000 --- a/site/guide/running-workflows.html +++ /dev/null @@ -1,165 +0,0 @@ - - - - - -Running workflows — Workflow Server - - - - - - -
    -
    - Workflow Server - - - -
    -
    - - - - - - -
    -

    Running workflows

    -

    Drive workflows in natural language. No tool names, no tokens to copy. Describe what you want; the agent matches your request, runs phases, and returns at every checkpoint.

    -

    A work package is the bundled workflow for planning and implementing one unit of work (for example a feature or issue).

    - -

    What to say

    -

    Start a workflow by naming the goal:

    - 
    Start a new work-package workflow for implementing user authentication
    - 
    Begin a work-package workflow for issue #42
    -

    Resume one — sessions live on disk, so this works across restarts and even across chat conversations:

    - 
    Resume the work-package workflow we were working on
    - 
    Continue the authentication work package from where we left off
    -

    Finish or wind one down:

    - 
    End the current work-package workflow
    - -

    What a run looks like

    -

    A session moves through the workflow's activities in order, pausing at checkpoints for your decisions:

    - -
    - - A session timeline - A timeline of five stages: the session starts, a planning activity runs, the workflow pauses at a checkpoint for your decision, an implementation activity runs, and the workflow completes. - - - - - - - - session starts - - activity - e.g. plan - - checkpoint - your decision - - activity - e.g. implement - - complete - - - - - - - - the rounded stage is a pause — nothing advances until you answer - -
    A session timeline. Activities run in sequence; checkpoints (rounded) pause the run for your decision, and your choice can change which activities follow. Real workflows have more activities and more checkpoints than this sketch.
    -
    - -

    Underneath, the agent follows the server's bootstrap procedure. You never manage this sequence; the IDE bootstrap rule routes workflow requests to the server. Tool-level detail: MCP tool reference and the home page overview.

    - -

    At a checkpoint

    -

    When the run reaches a checkpoint, the agent presents the decision with its options and waits. Answer it like any question — pick an option, or give the custom input it asks for. The server enforces the pause: the workflow cannot advance until a response is recorded, and checkpoints with an auto-advance default still respect the server-enforced timer before proceeding.

    - -

    Where the work lands

    -

    Each session owns a planning folder under your project's .engineering/artifacts/planning/<date-slug>/. Workflow artifacts — plans, analyses, review notes — are written there, alongside the session.json the server uses to track state. The folder name is the handle for resuming: "resume the authentication work package" finds the matching slug and continues that session.

    - -

    Next

    -

    If the agent is not picking up workflow requests, work through IDE setup first.

    -
    - - - - - - - - - - diff --git a/site/index.html b/site/index.html index c40fa869..c55dc2fb 100644 --- a/site/index.html +++ b/site/index.html @@ -12,23 +12,13 @@
    - Workflow Server + Workflow Server @@ -137,19 +121,121 @@

    How it works

    For users

    You speak in natural language. The agent matches your request to a workflow, works through its phases, and stops at checkpoints when you need to decide something. You never manage tool names or session tokens yourself.

      -
    1. Install and connect. Build the server and register it with your MCP client. See Getting started.
      2. -
    2. Add the IDE rule. One always-applied rule makes the agent call discover first. See IDE setup.
      3. -
    3. Run or resume. Say "start a work package" or "resume the workflow." See Running workflows.
      4. +
    4. Install and connect. Build the server and register it with your MCP client.
      5. +
    5. Add the IDE rule. One always-applied rule makes the agent call discover first.
      6. +
    6. Run or resume. Start, resume, or end a workflow in plain language.
    7. Answer checkpoints. When the run pauses, pick an option. The workflow cannot advance until you respond.
    +

    Setup, the bootstrap rule, and example phrases are in Getting started.

    For agent implementers

    The agent follows a bootstrap procedure returned by discover — you do not call MCP tools yourself; the IDE rule routes workflow requests here.

    -

    Tool reference (16 tools, generated from source). Protocol guide for call order, checkpoints, errors, and reference delivery. Workflows for orchestrator vs worker roles.

    +

    Tool reference (16 tools, generated from source). Protocol for call order, checkpoints, errors, and reference delivery. Workflows for orchestrator vs worker roles.

    +
    +

    The pieces

    +

    Your MCP client hosts the agent. The agent reaches the workflow-server through MCP; the server reads workflow definitions and owns session state in your project's workspace.

    + +
    + + System layers + Agents reach the server through sixteen MCP tools. Below the tool surface sit the enforcement layers, which consult workflow definitions read from the workflows directory and the session state persisted in the workspace. + + + + + + + + Agents (orchestrators and workers) + + MCP tool surface + 16 tools across six concerns + + Enforcement and resolution + fidelity layers · technique bundles + + Workflow definitions + workflows/ (read) + + Session state + session.json + .session-token + in your workspace + + + + + + + + + MCP + reads + owns + + +
    Agents only ever see the tool surface; the server validates every call against the workflow definition and persists canonical session state under .engineering/artifacts/planning/. Setup steps are in Getting started.
    +
    +
    + +
    +

    What a run looks like

    +

    A session moves through the workflow's activities in order, pausing at checkpoints for your decisions.

    +
    + + A session timeline + A timeline of session stages. Each activity uses techniques; steps follow those techniques; techniques consult linked resources (detail shown once below the first activity). Checkpoints pause the run for your decision. + + + + + + + + session starts + + activity + e.g. plan + + checkpoint + your decision + + activity + e.g. implement + + complete + + technique(s) + + step(s) + + resource(s) + + + + + + + + + + + + use(s) + consults + + + follows + + the rounded stage is a pause — nothing advances until you answer + +
    Activities run in sequence; each activity uses techniques. Step(s) follow those techniques, and techniques consult linked resources — shown once below the first activity. Checkpoints (rounded) pause the run for your decision. See Checkpoints.
    +
    +
    +

    Where to start

    Match your question to a page. This site is the browsable view; markdown in the repository is what you edit when you change the docs.

    @@ -159,21 +245,20 @@

    Where to start

    Your questionRead this - I am new — where do I begin?Getting started → IDE setup → Concepts → Running workflows - What is this project?Getting started or README (source) + I am new — where do I begin?Getting started → Definitions + What is this project?The pieces on this page or README (source) How do I install and connect the server?Getting started and SETUP (source) - How do I wire the IDE bootstrap rule?IDE setup - How do I run or resume a workflow?Running workflows - What are workflows, sessions, and checkpoints?Concepts + How do I wire the IDE bootstrap rule?Getting started + How do I run or resume a workflow?Getting started — example phrases + What are workflows, sessions, and checkpoints?Definitions · Checkpoints What tools does the server expose?Tool reference and API reference (source) - What do errors and warnings mean?Protocol guide - How do I author workflow definitions?Schema reference and Schema guide (source) - How is the system designed?Architecture overview and the six model pages linked from it - Why is it designed this way?Design rationale - How is the server implemented?Server internals + What do errors and warnings mean?Protocol + How do I author workflow definitions?Specifications · Schema reference + How is the system designed?Architecture overview and the model pages linked from it + How is the server implemented?Design overview — module map, request path, session store, quality gates What keeps agents faithful to a workflow?Workflow fidelity How do techniques declare protocol and bindings?Technique protocol (source) - How do I contribute to the server?Server anatomy and Development guide (source) + How do I contribute to the server?Server anatomy and Development guide (source) Where does new documentation belong?Documentation system (source) @@ -193,5 +278,6 @@

    Where to start

    + diff --git a/site/nav.js b/site/nav.js new file mode 100644 index 00000000..e87c7981 --- /dev/null +++ b/site/nav.js @@ -0,0 +1,20 @@ +/** Close nav dropdowns on selection; keep at most one section open at a time. */ +(function () { + const groups = document.querySelectorAll('.site-nav__group'); + if (!groups.length) return; + + groups.forEach((details) => { + details.addEventListener('toggle', () => { + if (!details.open) return; + groups.forEach((other) => { + if (other !== details) other.removeAttribute('open'); + }); + }); + + details.querySelectorAll('a').forEach((link) => { + link.addEventListener('click', () => { + details.removeAttribute('open'); + }); + }); + }); +})(); diff --git a/site/specifications.html b/site/specifications.html new file mode 100644 index 00000000..75c6bcb1 --- /dev/null +++ b/site/specifications.html @@ -0,0 +1,152 @@ + + + + + +Specifications — Workflow Server + + + + + + +
    +
    + Workflow Server + + + +
    +
    + + + + + + +
    +

    Specifications

    +

    Authoritative markdown specifications in the repository. Prefer the illustrated site pages where they exist; open the GitHub source when you need to edit or cite the canonical text.

    +

    Workflow and activity YAML shapes are also defined by the generated schema reference (from Zod sources). When a model page and a prose spec disagree on technique anatomy, the technique protocol wins.

    + +

    Architecture models

    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    SpecificationSummaryOn-site
    architecture.mdHub for the architectural models that govern server and agent interaction.Overview
    dispatch_model.mdThree agent layers — meta orchestrator, workflow orchestrator, and activity workers — and how work is spawned and resumed.Dispatch
    checkpoint_model.mdJust-in-time checkpoints: yield bubble-up, presentation, response timing, and resume with recorded effects.Checkpoints
    state_management_model.mdDeterministic transitions: the variable bag, checkpoint and worker mutations, and conditional branching.State
    artifact_management_model.mdWorkspace isolation, planning folders, artifact naming, and the server-synthesized artifacts contract.Artifacts
    resource_resolution_model.mdTechnique and resource resolution: :: paths, bundling, lazy-loaded reference material, and the meta/ fallback.Resolution
    workflow-fidelity.mdEnforcement layers — manifests, traces, seals, and schema validation — that keep agents on the defined path.Fidelity
    +
    + +

    Authoring contracts

    +
    + + + + + + + + + + + + + + + + +
    SpecificationSummary
    technique-protocol-specification.mdNormative contract for technique files: capability, inputs, outputs, protocol, rules, :: addressing, contract inheritance, Initial/Final composition, and delivery.
    orchestra-specification.mdGrammar and semantic constraints for workflow primitives — activities, steps, decisions, and loops — in the Orchestra definition language.
    schemas/README.mdSchema guide for authoring workflow definitions: manifest shapes, activity files, conditions, and validation conventions.
    +
    +
    + + + + + + + + + + + diff --git a/site/specs/architecture.html b/site/specs/architecture.html index 732f6ec0..27fa1309 100644 --- a/site/specs/architecture.html +++ b/site/specs/architecture.html @@ -4,7 +4,7 @@ Architecture — Workflow Server - + @@ -16,21 +16,11 @@ @@ -84,52 +68,9 @@

    Architecture

    -

    A small state machine wrapped in an MCP tool surface: agents call tools, the server enforces the workflow definition and owns session state on disk.

    -

    How workflow content is structured on disk — manifests, activities, techniques, resources — is documented in Workflows. The sections below cover how the server enforces runs.

    -

    Canonical source: docs/architecture.md (edit).

    - -
    - - System layers - Agents reach the server through sixteen MCP tools. Below the tool surface sit the enforcement layers, which consult workflow definitions read from the workflows directory and the session state persisted in the workspace. - - - - - - - - Agents (orchestrators and workers) - - MCP tool surface - 16 tools across six concerns - - Enforcement and resolution - fidelity layers · technique bundles - - Workflow definitions - workflows/ (read) - - Session state - session.json + .session-token - in your workspace - - - - - - - - - MCP - reads - owns - - -
    System layers. Agents only ever see the tool surface; the server validates every call against the workflow definition and persists canonical session state in your project's workspace. Agents never read or write state files themselves.
    -
    +

    The workflow-server is a small state machine wrapped in an MCP tool surface. Agents call tools; the server validates every request against the workflow definition, composes techniques and resources just in time, and persists canonical session state on disk in your project's workspace. The architecture is organized as models — dispatch, checkpoints, state, artifacts, resolution, and fidelity — so long-running, multi-agent runs stay bounded, pauses reach the user-facing agent, and transitions never depend on guesswork.

    -

    The six models

    +

    Models

    • 1. Hierarchical dispatch

      @@ -162,20 +103,6 @@

      6. Workflow fidelity

      Fidelity model
    - -

    Normative specifications

    -

    Two documents define the system's contracts precisely; they are the reference when a model page and an edge case disagree:

    -
      -
    • Technique protocol specification — the anatomy of a technique file (capability, inputs, outputs, protocol, rules), the :: addressing grammar, contract inheritance, Initial/Final protocol composition, and delivery.
      • -
    • Orchestra DSL specification — the workflow/activity definition language: step, decision, loop, and flow primitives, the EBNF grammar, and the semantic constraints.
      • -
    - -

    The implementation view

    -

    The models above state the guarantees; two further sections of this site show the machinery and the reasoning behind them:

    -
    @@ -190,5 +117,6 @@

    The implementation view

    + diff --git a/site/specs/artifact-management.html b/site/specs/artifact-management.html index 7a5d0c8e..99e496a9 100644 --- a/site/specs/artifact-management.html +++ b/site/specs/artifact-management.html @@ -16,21 +16,11 @@ @@ -140,5 +124,6 @@

    Git and submodule protocol

    + diff --git a/site/specs/checkpoints.html b/site/specs/checkpoints.html index 77d3b310..82baf576 100644 --- a/site/specs/checkpoints.html +++ b/site/specs/checkpoints.html @@ -16,21 +16,11 @@ @@ -84,8 +68,62 @@

    Just-in-time checkpoints

    -

    Checkpoints are declarative gates inside activities that halt the workflow until an external condition is met — usually your explicit confirmation. Background workers cannot ask you questions directly, so a checkpoint "bubbles up" the agent hierarchy to the user-facing agent, and the resolution travels back down.

    -

    Canonical source: docs/checkpoint_model.md. For the single-agent view, see the concepts guide.

    +

    Checkpoints are declarative gates inside activities that halt the workflow until an external condition is met — usually your explicit confirmation. The agent cannot skip past one: the server records the active checkpoint in session state and refuses to advance until it is resolved.

    +

    Canonical source: docs/checkpoint_model.md.

    + +

    Where you stay in control

    +

    A checkpoint is a step where the workflow deliberately stops until you decide something: approve a design, pick an option, confirm a commit.

    + +

    Single-agent flow

    +
    + + The checkpoint flow + A sequence with three participants: you, the agent, and the server. The agent reaches a checkpoint step and calls yield underscore checkpoint; the server records it. The agent calls present underscore checkpoint and receives the message and options, presents the decision to you, and you choose. The agent submits your choice with respond underscore checkpoint, then calls resume underscore checkpoint and continues working with any variable updates. + + + + + + + + You + + Agent + + Server + + + + + + + + + + + + + + + + + yield_checkpoint + checkpoint recorded, work pauses + present_checkpoint + message + options + presents the decision to you + your choice + respond_checkpoint → resume_checkpoint + + work continues with any variable updates from your choice + +
    The checkpoint flow with one agent. The agent yields at the checkpoint, fetches the message and options, presents the decision to you, submits your choice, and resumes.
    +
    + +

    Your choice can set workflow variables — picking "skip the audit" or "include migration" changes which activities and steps run afterwards. Some checkpoints define a default option and can auto-advance after a timeout; the server still enforces the timer.

    + +

    Multi-agent bubble-up

    +

    Background workers cannot ask you questions directly, so a checkpoint bubbles up the agent hierarchy to the user-facing agent, and the resolution travels back down.

    @@ -156,6 +194,7 @@

    Resuming

    Why this design

      +
    • Pause and presentation are separate — the worker records the pause with yield_checkpoint and steps aside; the user-facing agent later presents and responds. Nothing advances past an unresolved checkpoint, wherever it was raised.
    • Clean UI boundaries — hidden background agents never prompt you directly, so nothing freezes waiting on an invisible question.
    • Stateless hand-offs — the signed handle carries the linkage; intermediate agents relay it without parsing or storing checkpoint details.
    • Timing enforcement — minimum response times and server-enforced auto-advance timers prevent an agent from "answering" its own checkpoint instantly.
      • @@ -178,5 +217,6 @@

      Why this design

      + diff --git a/site/specs/dispatch.html b/site/specs/dispatch.html index 4c93d804..669e232a 100644 --- a/site/specs/dispatch.html +++ b/site/specs/dispatch.html @@ -16,21 +16,11 @@ @@ -84,7 +68,7 @@

      Hierarchical dispatch

      -

      Workflows run through three agent layers: user-facing orchestrator, background workflow orchestrator, and ephemeral activity workers.

      +

      Workflows run through three agent layers — meta orchestrator, workflow orchestrator, and activity workers — kept apart by what they must not share: user conversation, workflow state, and task context.

      Layer key: L0 = user-facing meta orchestrator · L1 = workflow orchestrator (state owner) · L2 = activity worker (task executor).

      Canonical source: docs/dispatch_model.md.

      @@ -141,11 +125,11 @@

      Responsibilities per layer

      Dispatch mechanics

      Each session is identified by a 6-character base32 session_index, deterministically derived from the planning-folder slug. Agents pass the index — never a token — on every authenticated call; the canonical state lives in the server-owned session.json.

      -

      The two hand-offs differ in one important way. Starting a workflow (L0 → L1) creates a child session: the server snapshots the parent's session under the child's parentSession field for trace correlation, and the child gets its own index. Spawning a worker (L1 → L2) shares the session: the worker uses the orchestrator's index directly, so both agents see a single canonical state. The actual spawning uses whatever sub-agent mechanism the host provides (Cursor's Task tool, for example); paused sub-agents are woken with the host's resume primitive.

      +

      The two hand-offs differ in one important way. Starting a workflow (L0 → L1) creates a child session: the server snapshots the parent's session under the child's parentSession field for trace correlation, and the child gets its own index. Spawning a worker (L1 → L2) shares the session: the worker uses the orchestrator's index directly, so both agents see a single canonical state. Fresh workers per activity keep task context disposable; embedded child sessions keep the whole work package in one resumable session.json despite the layering. The actual spawning uses whatever sub-agent mechanism the host provides (Cursor's Task tool, for example); paused sub-agents are woken with the host's resume primitive.

      The meta orchestrator can poll a dispatched workflow with get_workflow_status: blocked when a checkpoint is active, completed when no activities remain, active otherwise.

      Inline fallback

      -

      Hosts without background sub-agents run the same model inline: a single agent adopts each persona in turn within one conversation. The server's enforcement — checkpoint gates, manifests, traces — works identically; only the persona-switching mechanism changes.

      +

      Hosts without background sub-agents run the same model inline: a single agent adopts each persona in turn within one conversation. The server's enforcement — checkpoint gates, manifests, traces — works identically; only the persona-switching mechanism changes. Portability across MCP clients mattered more than mandating a particular execution topology.

      Checkpoints bubble up through these same layers — see the checkpoint model. Session state and the session.json file are covered in state management.

      @@ -166,5 +150,6 @@ + diff --git a/site/specs/resource-resolution.html b/site/specs/resource-resolution.html index 231bfd51..37d867bb 100644 --- a/site/specs/resource-resolution.html +++ b/site/specs/resource-resolution.html @@ -16,21 +16,11 @@ @@ -84,7 +68,7 @@

      Technique and resource resolution

      -

      Context windows are precious, so nothing loads that isn't needed. All behaviour is composed from techniques — markdown capability definitions referenced by ::-paths — resolved workflow-first with a shared meta fallback, delivered as bundles, and backed by reference material that loads only on demand.

      +

      Context windows are precious, so definitions arrive at the granularity of need — workflow metadata at get_workflow, one activity at get_activity, one technique per step at get_technique, resources only when a technique cites them. All behaviour is composed from techniques (markdown capability definitions referenced by ::-paths), resolved workflow-first with a shared meta fallback, delivered as bundles, and backed by reference material that loads only on demand.

      Canonical source: docs/resource_resolution_model.md. The normative file anatomy is the technique protocol specification.

      @@ -221,7 +205,7 @@

      Delivery at workflow and activity granularity

    • get_workflow — orchestrator bundle: workflow-declared refs plus core orchestrator techniques (engine traversal, checkpoints, dispatch, discipline)
    • get_activity — worker bundle: activity refs, inherited techniques.activity from the workflow, plus core worker techniques (yield/resume, finalize, conduct rules)
    -

    Each bundle groups resolved content into three buckets. When a single technique is delivered, ancestor Initial / Final protocol blocks wrap the technique body recursively and the server renumbers the combined sequence.

    +

    Each bundle groups resolved content into three buckets. When a single technique is delivered, ancestor Initial / Final protocol blocks wrap the technique body recursively and the server renumbers the combined sequence. In persistent-context mode, reference-not-repeat delivery replaces already-delivered content with unchanged hash markers; fetch recording warns when a manifested step was never loaded.

    @@ -361,5 +345,6 @@ + diff --git a/site/specs/state-management.html b/site/specs/state-management.html index 866f1e41..cb8ea1e5 100644 --- a/site/specs/state-management.html +++ b/site/specs/state-management.html @@ -16,21 +16,11 @@ @@ -84,7 +68,7 @@

    State management and deterministic transitions

    -

    The workflow never asks the model to guess what happens next. A schema-validated variable bag holds the state; transitions are evaluated against it in declaration order; the first condition that matches wins. Conversational context plays no part in routing.

    +

    The workflow never asks the model to guess what happens next. A schema-validated variable bag holds the state; transitions are evaluated against it in declaration order; the first condition that matches wins. Conversational context plays no part in routing. Transitions, artifact contracts, binding provenance, and delivery payloads are all computed from definitions and state — same inputs, same path, with model judgment reserved for the work itself.

    Canonical source: docs/state_management_model.md.

    @@ -164,5 +148,6 @@ + diff --git a/site/specs/workflow-fidelity.html b/site/specs/workflow-fidelity.html index 50ee8bc8..f092e2a7 100644 --- a/site/specs/workflow-fidelity.html +++ b/site/specs/workflow-fidelity.html @@ -16,21 +16,11 @@ @@ -132,7 +116,7 @@

    The hard gates

    Checkpoint gate (L2). While a checkpoint is active, transition tools hard-fail; only present_checkpoint and respond_checkpoint are exempt. Responses are validated against the checkpoint definition, and timing is enforced — a minimum response delay for user-answered checkpoints, the full autoAdvanceMs timer for auto-advanced ones — so an agent cannot instantly answer its own question. Details in the checkpoint model.

    The advisory layers

    -

    Layers 3-6 warn rather than block. Warnings appear in _meta.validation and the trace. See protocol guide for how to read them.

    +

    Layers 3–6 warn rather than block. Only checks that are cheap and certain hard-stop execution; manifest completeness, version drift, and fetch coverage surface warnings in _meta.validation and the trace because the server can verify observable consistency, not that work was done well. See Protocol for how to read them.

    @@ -169,5 +153,6 @@

    Honest limitations

    + diff --git a/site/specs/workflows.html b/site/specs/workflows.html index b97ebe54..72199949 100644 --- a/site/specs/workflows.html +++ b/site/specs/workflows.html @@ -16,21 +16,11 @@ @@ -87,26 +71,12 @@

    Workflow architecture

    Workflows are declarative files, not code. This page explains what each file type means, how the pieces connect, and what the server delivers to the agent as work progresses.

    For server enforcement (checkpoints, dispatch, fidelity), see architecture overview. For file shapes, see the schema reference.

    - -

    Overview

    Think in two layers:

    • On disk — a workflow is a folder of YAML and markdown. Nothing in it is executable code; the files describe a process the agent follows step by step.
      • -
    • At runtime — the agent does not open those files. It calls MCP tools, and the server returns one piece at a time: the workflow overview, then the current activity, then each technique as the worker reaches it.
      • +
    • At runtime — the agent does not open those files. It calls MCP tools, and the server returns one piece at a time so context stays on the work in front of it — workflow overview, then the current activity, then each technique as the worker reaches it (Resolution).
    -

    Delivering content in small pieces keeps the agent's context focused on the work in front of it. See progressive disclosure in Design rationale for why.

    @@ -341,7 +311,7 @@

    Step kinds

    kind: checkpoint pause for user - decision; see Concepts + decision; see Checkpoints kind: loop repeat nested steps @@ -358,15 +328,14 @@

    Step kinds

    - +
    LayerWhen it runsEffectWhat to do
    techniqueReference to a capability by :: path, with optional input bindingsCall get_technique for the step (or use content already bundled in get_activity), follow the protocol, record outputs
    actionOne or more inline actions (validate, message, …)Execute the listed actions against current variables; the server does not interpret action verbs
    checkpointA declared pause with options and effectsCall yield_checkpoint; orchestrator presents and respond_checkpoint; worker resume_checkpoint — see checkpoints in Concepts
    checkpointA declared pause with options and effectsCall yield_checkpoint; orchestrator presents and respond_checkpoint; worker resume_checkpoint — see Checkpoints
    loopA nested step list with an exit conditionRepeat the nested steps until the condition is satisfied or the loop declares completion

    Techniques

    -

    A technique is a markdown file that explains how to do one job — capability, inputs, outputs, protocol, and rules. Activity steps refer to techniques by path; the agent never reads those files from the repository directly.

    -

    Path resolution, composition, and delivery are on Resolution. This page covers on-disk layout only.

    +

    A technique is a markdown file with a fixed shape — capability, inputs, outputs, protocol, and rules — not an ambient agent skill that loads when a description matches. Activity steps name techniques by :: path; the server composes, binds, and delivers them per step. The agent never reads technique files from the repository directly. Path resolution and bundling are on Resolution.

    @@ -391,6 +360,9 @@

    Techniques

    The standard sections in a technique file. Full rules are in the technique protocol specification (source).
    +

    Compared to agent skills

    +

    Skills suit opt-in guidance: a short description and instructions the model loads when a request seems to match. Orchestrated workflows need a contract the server can schema-check, merge with ancestor protocols, and deliver step by step. Bulky templates and API guides stay in resources/ and load via get_resource only when a running technique links to them — the protocol states what to execute; reference material is separate (Resources).

    +

    Resources

    A resource is long-form reference material — templates, checklists, tables — stored as markdown under resources/. Techniques link to resources instead of inlining them; the agent calls get_resource only when a running technique needs the linked material.

    Resolution rules, section anchors, and cross-workflow prefixes are on Resolution.

    @@ -449,13 +421,13 @@

    Runtime delivery

  • Checkpoints — the worker yields, the orchestrator presents your choice, and the worker resumes before continuing
  • Resources — load only when a technique the worker is executing links to one
    • -

    Tool call order, bundling, and errors are in the protocol guide. Technique and resource resolution are on Resolution.

    +

    Tool call order, bundling, and errors are in Protocol. Technique and resource resolution are on Resolution.

    Normative references

    -

    JSON shapes: schema reference. Authoritative prose specs: architecture overview → Normative specifications.

    +

    JSON shapes: schema reference. Authoritative prose specs: Specifications.

    Next

    -

    Concepts covers sessions and checkpoints from a user perspective. Dispatch explains how orchestrators and workers run those workflows.

    +

    Definitions covers sessions from a user perspective. Checkpoints explains deliberate pauses and your choices. Dispatch explains how orchestrators and workers run those workflows.

    @@ -472,5 +444,6 @@

    Next

    + diff --git a/site/style.css b/site/style.css index ad98b2b6..76676aa0 100644 --- a/site/style.css +++ b/site/style.css @@ -332,9 +332,13 @@ main, } .takeaway { - font-weight: 600; - color: var(--text); - margin-bottom: var(--space-2); + margin: 0 0 var(--space-3); + padding: var(--space-2) var(--space-3); + background: var(--bg-inset); + border-left: 3px solid var(--accent); + border-radius: 0 var(--radius) var(--radius) 0; + font-size: 0.95rem; + color: var(--text-muted); } .contributor-note { diff --git a/skills-lock.json b/skills-lock.json new file mode 100644 index 00000000..d3933744 --- /dev/null +++ b/skills-lock.json @@ -0,0 +1,29 @@ +{ + "version": 1, + "skills": { + "design-taste-frontend": { + "source": "Leonxlnx/taste-skill", + "sourceType": "github", + "skillPath": "skills/taste-skill/SKILL.md", + "computedHash": "6d838b246d0e35d0b53f4f23f98ba7a1dd561937e64f7d0c7553b0928e376c3e" + }, + "imagegen-frontend-web": { + "source": "Leonxlnx/taste-skill", + "sourceType": "github", + "skillPath": "skills/imagegen-frontend-web/SKILL.md", + "computedHash": "65f5ae59fa317567809438310b1c54f78cd133426deb43e4d3d4ca4c8f541628" + }, + "minimalist-ui": { + "source": "Leonxlnx/taste-skill", + "sourceType": "github", + "skillPath": "skills/minimalist-skill/SKILL.md", + "computedHash": "08873a3131d3be27bef9bf3304b310b16b44ca6e3561aebe532797be3443f6bd" + }, + "stitch-design-taste": { + "source": "Leonxlnx/taste-skill", + "sourceType": "github", + "skillPath": "skills/stitch-skill/SKILL.md", + "computedHash": "13322f38406cd3abf16ba45e35bdc9b18002d0153a79b4612b97aefc65d5a335" + } + } +} From 25fce19e893384ed53bdba988bc83fa601370d99 Mon Sep 17 00:00:00 2001 From: Mike Clay Date: Sat, 11 Jul 2026 11:56:50 +0100 Subject: [PATCH 12/12] Fix home run diagram relationships and layout. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Show activity → step → technique → resource chain with clearer arrows, correct follows/apply/consult labels, and remove redundant in-diagram note. --- site/index.html | 33 +++++++++++++++------------------ 1 file changed, 15 insertions(+), 18 deletions(-) diff --git a/site/index.html b/site/index.html index c55dc2fb..2804e79b 100644 --- a/site/index.html +++ b/site/index.html @@ -185,9 +185,9 @@

    The pieces

    What a run looks like

    A session moves through the workflow's activities in order, pausing at checkpoints for your decisions.

    - + A session timeline - A timeline of session stages. Each activity uses techniques; steps follow those techniques; techniques consult linked resources (detail shown once below the first activity). Checkpoints pause the run for your decision. + A timeline of session stages. Each activity follows its steps; steps apply techniques; techniques consult linked resources (detail shown once below the first activity). Checkpoints pause the run for your decision. @@ -207,32 +207,29 @@

    What a run looks like

    e.g. implement complete - - technique(s) - - step(s) - - resource(s) + + step(s) + + technique(s) + + resource(s) - - - + + + - use(s) - consults + follows + apply + consult - - follows - - the rounded stage is a pause — nothing advances until you answer -
    Activities run in sequence; each activity uses techniques. Step(s) follow those techniques, and techniques consult linked resources — shown once below the first activity. Checkpoints (rounded) pause the run for your decision. See Checkpoints.
    +
    Activities run in sequence; each activity follows its step(s), steps apply techniques, and techniques consult linked resources — shown once below the first activity. Checkpoints (rounded) pause the run for your decision. See Checkpoints.