AI workflow format reference

Skafold uses three distinct JSON contracts. Do not substitute one for another.

New-project seed

A project seed creates a new project:

{
  "format": "skafold-project-seed",
  "schemaVersion": "1.0",
  "project": {},
  "pages": []
}

It may include:

• generator: provider, model, skill version, and generation time.
• project: project name, summary, goals, audiences, constraints, delivery notes, and structured brief lists.
• pages: routes or application screens and their planning fields and Section placements.
• globalSections: reusable definitions and organisational dividers.
• journeys: focused actor-led paths.
• architecture: implementation items and direct relationships.
• design: visual direction and system guidance.
• assumptions and openQuestions.

Seeds may include bounded node bounds and semantic connector handles in the optional root layout field. They exclude raw canvas and internal application state.

Published AI Context

An existing project’s bearer URL returns:

{
  "format": "skafold-ai-context",
  "schemaVersion": "1.0",
  "contextRevision": 4,
  "contextHash": "sha256:…",
  "publishedAt": "2026-08-21T03:00:00Z",
  "project": {},
  "protocol": {},
  "frames": {}
}

Every frame has its own hash and complete semantic data. The protocol object identifies the snapshot's workflow version and accepted update versions. AI tools should fetch the URL immediately before planning and use the current locally installed Project Importer.

Existing-project frame update

One update file can target one frame, any combination, or all frames:

{
  "format": "skafold-frame-update",
  "schemaVersion": "1.0",
  "protocolVersion": "1.5",
  "basedOn": {
    "contextRevision": 4
  },
  "frames": {
    "site-map": {
      "mode": "replace",
      "frameHash": "sha256:…",
      "data": {
        "pages": []
      }
    }
  }
}

The supported frame keys are:

• project-overview
• site-map
• user-journeys
• sections
• page-layouts
• technical-architecture
• design-guidance

Each present key is a complete replacement target. Missing items inside that frame are removals. Omitted frame keys are untouched.

IDs and references

Use stable lowercase kebab-case IDs.

• A page parentId references another declared page.
• A page placement globalSectionId references a non-divider item in globalSections.
• A reusable definition groupId references a kind: "separator" item.
• A journey step pageId references a declared page.
• Architecture relationships reference declared architecture items.
• IDs are unique within their collection.

Preserve IDs for unchanged items. Stable IDs let Skafold retain relationships and distinguish edits from removal and recreation.

Structure and Page Hierarchy

Structure owns the complete page list, identity, paths, purpose, and direct hierarchy. Page Hierarchy owns page planning and ordered placements.

When an update adds or removes a page, include both site-map and page-layouts so dependencies are explicit. A newly added Structure page may begin with an empty Page Hierarchy plan.

Sections and placements

Define reusable components once in globalSections. Keep shared layout, notes, tags, buildGuidance, grouping, and definition status on that definition.

Page placements contain id, name, globalSectionId, optional instanceName, and optional independent placement statusColor.

Accepted explicit status colours are blue, purple, amber, red, and green. Omit status when not started. Do not generate legacy gray or completed fields.

Conflict behavior

The AI copies the current hash for every targeted frame. Skafold rejects the update if any target changed after generation. An unrelated revision does not block the file when all targeted hashes still match.

Refetch the same AI Context URL and regenerate when a target is stale.