floop 2.0.0

Project/version review loop CLI and agent skill for AI artifacts

floop-client

AI artifacts need review. floop-client is the review-loop CLI that connects fppt decks and fdesign prototypes to floop-server for structured feedback — without touching artifact internals.

---

The Problem: The "Screenshot Ping-Pong" Trap

You built a beautiful prototype with fdesign or a polished deck with fppt. Now you need feedback from your team, your client, or your stakeholders. What happens next?

Screenshots in Slack. PDFs over email. "Can you make the button bluer?" scattered across three different threads. Feedback arrives out of context, untethered from the specific page or component it references. You spend more time chasing down what people meant than actually improving the artifact.

Why does this happen? AI tools are great at building artifacts, but they have no built-in mechanism for reviewing them. Every team cobbles together their own ad-hoc feedback loop — and every loop leaks context.

WITHOUT floop-client

  Build v1  →  Screenshot → Slack  →  "Looks good but..."  →  Where was this?
  Build v2  →  PDF export → Email  →  "Change the header"  →  Which page?
  Build v3  →  Loom video → Notion  →  "The spacing is off" →  Which component?

  Result: Feedback is everywhere and nowhere. Context is lost.

WITH floop-client

  Build v1  →  floop review upload  →  shareUrl  →  Reviewers comment inline
  Fixes     →  Build v2  →  floop review upload  →  New shareUrl
  Comments  →  floop comments       →  Route to fppt/fdesign  →  Fix & resolve

  Result: Every comment is anchored to a version, a page, and a DOM element.

---

What floop-client Does

floop-client is the review-loop layer between your AI-built artifacts and your reviewers. It does not build decks or prototypes — it creates version containers, uploads them to floop-server, fetches structured comments, and resolves them after fixes.

It is intentionally artifact-agnostic. fppt owns presentation logic. fdesign owns prototype logic. floop-client owns the review pipeline.

flowchart LR
    subgraph "Build"
        fppt["fppt<br/>Decks"]
        fdesign["fdesign<br/>Prototypes"]
    end

    subgraph "Review Loop"
        floop["floop-client<br/>Projects · Versions · Upload · Comments"]
    end

    subgraph "Server"
        server["floop-server<br/>Review UI · Comment Threads"]
    end

    fppt -->|"copies build into version"| floop
    fdesign -->|"copies build into version"| floop
    floop -->|"upload"| server
    server -->|"comments"| floop
    floop -->|"route fixes"| fppt
    floop -->|"route fixes"| fdesign

    style floop fill:#e8f4fd,stroke:#2563EB,stroke-width:2px

---

Why floop-client

For Makers & Founders

You ship fast. Feedback shouldn't slow you down.

Stop juggling screenshots and Slack threads. Publish a version with one command, share a single link, and get structured, anchored feedback that tells you exactly which page and element each comment refers to.

For Teams (Designers & Developers)

Review cycles need structure, not chaos.

Every comment carries a priority, labels (bug, copy, layout, responsive, accessibility), and a DOM anchor. No more "the button on that one page" — reviewers click, comment, and the context travels with the feedback. After fixes, resolve comments to close the loop.

---

Use Cases

Scenario 1: Client Review Round

Problem: You built a prototype with fdesign. The client wants to review it. You export screenshots, paste them into a Google Doc, and wait. Three days later, you get back 47 comments — half of them referencing "the blue section" on "that page."

floop-client Solution: Run floop review upload --project my-app --version v1. Share the shareUrl. The client clicks through the prototype on floop-server, clicks any element, and leaves anchored comments. You run floop comments to fetch them all, grouped by page and priority.

Scenario 2: Deck Stakeholder Approval

Problem: You built a presentation with fppt. Marketing, Legal, and the CEO all need to sign off. Each sends feedback in a different format. You spend hours consolidating.

floop-client Solution: One shareUrl for all stakeholders. Comments are threaded, labeled, and anchored to specific slides. Legal flags get a legal label. Marketing feedback gets copy. You address them, publish v2, and resolve each comment — full audit trail.

Scenario 3: Continuous Iteration

Problem: You're iterating fast with AI. Every build is a new version. You need to track what changed, what was reviewed, and what's still open — across multiple versions.

floop-client Solution: Each version is independent with its own comment thread. floop comments --version-id <id> fetches feedback for a specific version. Reviewers can compare versions side-by-side on floop-server. Nothing falls through the cracks.

---

Features

• Local Version Containers: Create named projects and versions under .floop/ — artifact services copy their build output in.
• One-Command Upload: floop review upload zips and publishes a version to floop-server, returning a shareUrl.
• Structured Comments: Fetch anchored, labeled, prioritized feedback — every comment knows its page, element, and viewport.
• Comment Resolution: floop resolve marks feedback as addressed after fixes are published.
• Local Preview: floop preview serves version directories locally for quick inspection before upload.
• Multi-Agent Support: Install skills into 7 AI agent platforms with floop enable.

Responsibility Boundary

floop-client is intentionally boring. It should remain artifact-agnostic.

Owned by floop-client	Owned by fppt / fdesign
.floop/ workspace	.fppt/ deck workspace
Project & version containers	.fdesign/ prototype workspace
floop review upload	Deck YAML validation
floop comments	Design token validation
floop resolve	Component & sitemap logic
floop preview	Theme systems
Server project binding	Artifact build output

Supported Agents

Agent	Command
GitHub Copilot	floop enable copilot
Cursor	floop enable cursor
Claude Code	floop enable claude
Trae IDE	floop enable trae
Qwen Code	floop enable qwen-code
OpenCode	floop enable opencode
OpenClaw	floop enable openclaw

---

Installation

pip install floop

Verify:

floop --version

---

Quick Start

# 1. Initialize workspace
cd your-project
floop init

# 2. Install skills into your AI agent
floop enable copilot     # or: cursor, claude, trae, qwen-code, opencode, openclaw

# 3. Create a local project and version
floop projects create my-review
floop versions create v1 --project my-review --artifact-type fdesign --entrypoint index.html

# 4. Let fppt/fdesign copy artifact files into the version directory
#    (your AI agent handles this automatically)

# 5. Configure review server and upload
floop review set --project my-review
floop review upload --project my-review --version v1 --json-output
# → shareUrl: https://floop-server.vercel.app/review/...

# 6. Share the link with reviewers, then fetch comments
floop comments --project my-review --version-id <server-version-id> --json-output

# 7. After fixes are published, resolve addressed comments
floop resolve <comment-id> --project my-review --version-id <server-version-id> --status resolved

---

Workspace

.floop/
├─ floop.env              # Server URL + API key (no project key)
├─ config.json            # Workspace metadata
└─ projects/
   └─ <project>/
      ├─ project.json     # Local metadata + serverProject binding
      └─ versions/
         └─ <version>/
            ├─ version.json
            └─ ...artifact files copied by fppt/fdesign...

---

Review Loop

┌── Build ──→ Version Container ──→ Upload ──→ Share ──→ Comments ──→ Fix ──┐
│                                                                           │
└───────────────────────────────────────────────────────────────────────────┘

1. Artifact service (fppt/fdesign) builds and checks its output.
2. Agent creates a local floop project/version container.
3. Agent verifies the local project has the correct serverProject binding.
4. If missing, agent runs floop review set --project <project>.
5. Artifact service copies its build output into the version directory.
6. floop review upload zips and uploads to floop-server.
7. Agent shares shareUrl with the user.
8. Agent fetches comments with floop comments.
9. Agent routes fixes to fppt, fdesign, or floop-client.
10. After a fixed version is uploaded, agent resolves addressed comments.

---

For Contributors

floop-client is the review-loop layer in the floop ecosystem. We welcome contributors who want to expand agent platform support or harden the upload/comment pipeline.

Getting Started

# 1. Fork and clone the repository
git clone https://github.com/lijma/floop-client.git
cd floop-client

# 2. Install inside a virtual environment for development
pip install -e ".[test]"

# 3. Run the test suite (floop-client maintains 100% coverage)
pytest --cov=floop --cov-report=term-missing --cov-fail-under=100

# 4. Want to add a new AI Agent to `floop enable`?
# Add yours directly in: src/floop/adapters.py

---

Star History

---

License

This project is licensed under the MIT License.