Skip to content

Architecture

How It Works

floop operates on one principle: a shared .floop/ directory that every AI agent, the CLI, and the preview server read from.

Source files (commit these)          Generated artifacts (gitignored)
─────────────────────────────        ─────────────────────────────────
.floop/tokens/*.tokens.json   ──→   .floop/build/tokens/tokens.css
.floop/components.yaml        ──→   .floop/build/components/components.js
                                    .floop/build/components/index.html
.floop/sitemap.md             ──→   .floop/journey-map.csv
                                    .floop/build/journey/<domain>/*.html

The CLI validates and generates. The AI agent fills in content. The preview server serves.

Directory Structure

.floop/
├── config.json               # Project metadata
├── .gitignore                # Excludes build/ and versions/
│
├── tokens/                   # ← AI writes here (W3C DTCG JSON)
│   ├── global.tokens.json
│   ├── semantic.tokens.json
│   └── component.tokens.json
│
├── prd.md                    # ← AI writes here (YAML frontmatter + Markdown)
├── sitemap.md                # ← AI writes here
├── components.yaml           # ← AI writes here (YAML)
├── journey-map.csv           # ← generated by floop prototype init
│
├── build/                    # ← generated artifacts
│   ├── tokens/
│   │   ├── design-tokens.html
│   │   └── tokens.css        # ← every journey page links this
│   ├── components/
│   │   ├── index.html
│   │   └── components.js     # ← every journey page scripts this
│   └── journey/
│       └── <domain>/
│           └── <page>.html
│
└── versions/                 # ← named snapshots
    └── v1.0/
        ├── meta.json
        └── build/

Quality Pipeline

The quality flow has two directions:

Forward (creation time):
  Token source → floop token validate → floop token view → tokens.css
  Component YAML → floop component validate
  Prototype HTML → floop prototype validate

Backward (after creation):
  .floop/build/journey/<page>.html
        ↓
  floop journey check
        ↓
  4 checks: head links, token refs, raw tags, component coverage
        ↓
  errors → agent fixes → re-check

Token Resolution

W3C DTCG tokens use {path} references. floop resolves them recursively across all three files:

global.tokens.json:    color.blue-500  = #2563EB
semantic.tokens.json:  color.primary   = {color.blue-500}  → resolves to #2563EB
component.tokens.json: button.bg       = {color.primary}   → resolves to #2563EB

→ tokens.css: --button-bg: #2563EB;

floop token validate catches: - Unresolved references ({color.nonexistent}) - Missing required fields ($type, $value) - Unrecognized $type values - Circular references (A → B → A)

Backward Check Logic

floop journey check scans the HTML file in one pass:

  1. Head links — substring search for tokens.css and components.js in <head>
  2. Token refs — regex var\((--[a-zA-Z0-9_-]+) → validate each against all token CSS variables
  3. Raw tag detection — for each component with html_tag set:
  4. Find all <tag …> elements with re.finditer
  5. For each element, check attributes for data-component="comp-id" or class containing comp-id as a space-separated token
  6. Flag only elements where neither is present (one error per component type)
  7. Component coverage — check each component id against full HTML string

Version Mechanism

trunk (working)                    named snapshots
.floop/build/         ───────→    .floop/versions/v1.0/build/
                                  .floop/versions/v1.1/build/
                      copy on
                      version create

The preview server serves .floop/ at root. The version dropdown in the UI switches the iframe base path between build/ and versions/<name>/build/.

Agent Skill Architecture

floop enable <agent> writes two types of content, adapted to each agent's native format:

Content Always-on? What it contains
INSTRUCTION Yes Available commands, key constraints, never-do rules
SKILL On-demand Full A→F iterative workflow with decision logic

The INSTRUCTION is loaded every session. The SKILL is loaded when the agent starts a prototype task.

Adapter implementations in adapters.py:

Adapter Base class Skill delivery
CopilotAdapter AgentAdapter Separate .md files in .github/skills/, instruction in .github/instructions/
CursorAdapter AgentAdapter Separate .mdc files in .cursor/rules/
ClaudeAdapter AgentAdapter Separate .md files in .claude/skills/, merged into CLAUDE.md
TraeAdapter AgentAdapter All content inlined into .trae/project_rules.md
QwenCodeAdapter _AgentsMdAdapter Merged into AGENTS.md only
OpenCodeAdapter _AgentsMdAdapter Skill file in .opencode/skills/ + merged into AGENTS.md
OpenClawAdapter _AgentsMdAdapter Skill file in .openclaw/skills/ + merged into AGENTS.md

_AgentsMdAdapter uses HTML comment markers (<!-- floop:skills --> / <!-- /floop:skills -->) in AGENTS.md for idempotent updates.