DEV Community: WonderLab

Workflow Series (04): Multi-Agent Coordination — Orchestrator Boundaries, Concurrency Control, and Context Isolation

WonderLab — Thu, 02 Jul 2026 02:17:55 +0000

Orchestrator Responsibility Boundaries

Unclear division between the Orchestrator (main Agent) and Subagents is the most common design problem in multi-agent workflows.

The Orchestrator does three things:

1. Decide: read state, determine the next step
2. Dispatch: spawn subagents, pass task prompts
3. Collect: read subagent output files, update state

It doesn't execute business logic (analyze bugs, write code, query logs), read raw files, or modify business data. Those belong to subagents.

The main Agent receives only structured conclusions (JSON). Subagents report through output.json, not message streams.

# ✅ Correct: main Agent reads structured conclusion
result = json.loads(Path("phase3/analysis_final.json").read_text())
if result["confidence"] >= 95:
    proceed_to_phase4()

# ❌ Wrong: main Agent reads raw logs
log_content = Path("crash.log").read_text()  # 100k lines into the main Agent's context
decision = llm.analyze(log_content)           # this is subagent work

This boundary produces two benefits: the main Agent's context stays manageable (state and conclusions, no raw data); subagents' business logic can be tested independently, without the main Agent's session history.

Subagent Design Principles

Principle 1: Input Completeness

The task prompt must contain everything the subagent needs to complete its task.

# ❌ Incomplete task prompt
Analyze the root cause of this bug. Refer to previous analysis results.

# ✅ Complete task prompt
## Task
Analyze the root cause of the following bug.

## Input
Bug info:
{{ bug_info.summary }}
{{ bug_info.stack_trace }}

Log directory: {{ log_dir }}

## Output requirements
Write to analysis_final.json, format:
{"confidence": float, "root_cause": str, "evidence": [str]}

"Refer to previous analysis results" requires the subagent to access the main Agent's context history — which doesn't exist in an isolated session. Each subagent knows only what's in its task prompt.

Principle 2: Output Contract Strictness

Subagents must write their output files in the declared JSON Schema. The main Agent's routing logic depends on this schema; missing fields or wrong types break the decision logic.

# Subagent output schema (defined in templates/)
OUTPUT_SCHEMA = {
    "passed": bool,           # required — main Agent routing depends on this
    "confidence": float,      # required — range 0-1
    "root_cause": str,        # required
    "evidence": list[str],    # required
    "error": str | None       # required on failure
}

Principle 3: Structured Error Output on Failure

On failure, subagents must still write an output file with passed=false.

{
  "passed": false,
  "error": "Log file not found: /workspace/logs/crash_20260601.log",
  "confidence": 0,
  "root_cause": null,
  "evidence": []
}

A missing output file looks like a timeout to the main Agent. Structured error output lets the main Agent distinguish "subagent failed" from "subagent timed out" and respond differently.

Fan-out / Fan-in Concurrency Control

Fan-out Design

Fan-out means one trigger point spawns N concurrent subagents. Two hard constraints:

Constraint 1: Each subagent writes a different output file

# ✅ Correct: each candidate writes to its own file
candidates = ["candidate_a", "candidate_b", "candidate_c"]
for c in candidates:
    spawn_subagent(
        task_prompt=build_prompt(c, bug_info),
        output_file=f"phase4/{c}.json"  # unique filename
    )

# ❌ Wrong: all candidates write to the same file (concurrent write conflict)
spawn_subagent(task_prompt=..., output_file="phase4/result.json")
spawn_subagent(task_prompt=..., output_file="phase4/result.json")  # conflict!

Constraint 2: The main Agent waits for all subagents to complete

After fan-out, the main Agent enters a waiting state and doesn't proceed. When no async runtime is available, polling works:

def wait_all_candidates(candidates: list[str], timeout: int = 300) -> dict:
    results = {}
    deadline = time.time() + timeout

    while len(results) < len(candidates) and time.time() < deadline:
        for c in candidates:
            if c not in results:
                output_file = Path(f"phase4/{c}.json")
                if output_file.exists():
                    results[c] = json.loads(output_file.read_text())
        time.sleep(5)

    return results

Fan-in: Failure Strategy

When some subagents fail at fan-in, two strategies:

fail-fast (abort on any failure)

# For: all branch results are required; one failure makes the whole batch meaningless
phase_parallel_analysis:
  fan_in_strategy: fail-fast
  on_any_failure: trigger_gate_A

When to use: Three subagents each retrieve data from different sources. Missing any one source makes further analysis impossible.

collect-all (aggregate everything, including failures)

# For: partial success is enough; select the best from passing results
phase_4_fix:
  fan_in_strategy: collect-all
  selection_criteria:
    require_any_passed: true
    select_by: max_test_coverage
  on_all_failed: trigger_gate_B

When to use: Three code-fix candidates run concurrently. One passing tests is sufficient. Failed candidates are discarded. Only if all three fail does the human gate trigger.

Selection Principle

All branch results are required          → fail-fast
Partial success is sufficient            → collect-all (code fix, candidate generation)
Comparing multiple results for quality   → collect-all (select best)

The Phase 4 fix in a Bug fix workflow uses collect-all: three candidates run concurrently, the one with highest test coverage among passing candidates is selected, and the human gate only triggers when all three fail.

Context Isolation

Subagents must run in isolated sessions with no access to the main Agent's conversation history.

The main Agent's context holds the full workflow history: all file contents, all subagent raw outputs, all intermediate decisions. Passing this to a subagent writing one patch causes context to balloon from a few thousand tokens to tens of thousands, doubles token cost, and lets irrelevant history degrade the subagent's focus.

Information flows in two directions:

Main Agent
  │
  │ task prompt (only the fields the subagent needs)
  ▼
Subagent (isolated session, no history)
  │
  │ output_file (JSON at agreed path)
  ▼
Main Agent (reads file, not conversation history)

The subagent knows what's in its task prompt and the agreed output path. It doesn't know what the main Agent did, how far the workflow has progressed, or what other subagents produced.

If a subagent needs to "understand the background" to complete its task, the task prompt is incomplete. Put that background in explicitly — don't count on the subagent accessing history it can't see.

Design Checklist

Orchestrator responsibilities

[ ] Main Agent reads only structured JSON output — no raw logs or long text
[ ] Main Agent doesn't execute business logic (analysis, writing code, queries)
[ ] Routing decisions depend on the state file and subagent output, not conversation history

Subagent design

[ ] Task prompt contains all fields the subagent needs (no implicit context dependencies)
[ ] Output schema is declared in templates/ and includes a passed field
[ ] On failure, the subagent still writes {"passed": false, "error": "..."} to the output file

Concurrency control

[ ] Each subagent in a fan-out writes to a unique output file path
[ ] Fan-in strategy is explicitly labeled fail-fast or collect-all
[ ] collect-all has defined selection_criteria and on_all_failed behavior

Context isolation

[ ] Subagents run in isolated sessions with no access to the main Agent's history
[ ] All background information the subagent needs is explicitly in the task prompt

Summary

The Orchestrator only decides and dispatches: reads JSON conclusions, spawns subagents, collects JSON conclusions — keeping context manageable is the core objective, not "being smart"
Fan-in strategy determines workflow resilience: solution-space problems (code fix) use collect-all; all-or-nothing problems (data collection) use fail-fast — getting this wrong either blocks on a single failure or wastes time on impossible tasks
Context isolation is quality assurance: extra context is noise, not help; if a subagent needs background to do its job, that background belongs explicitly in the task prompt

Check out PrimeSkills — a curated marketplace of AI agents and skills that have been validated in real-world, enterprise-grade workflows. No fluff, just what actually works.

Find more useful knowledge and interesting products on my Homepage

Open Source Project of the Day (#112): obsidian-skills — Official Agent Skills by Obsidian's CEO, So Agents Stop Breaking Your Vault

WonderLab — Thu, 02 Jul 2026 02:14:13 +0000

Introduction

"Most agents treat Obsidian vaults as plain folders and don't understand Obsidian's syntax. They produce notes that either corrupt existing formatting or fail to render correctly in Obsidian."

This is article #148 in the Open Source Project of the Day series. Today's project is obsidian-skills — the official AI Agent skill collection written by Obsidian CEO Steph Ango (kepano).

You ask Claude Code to create some notes in your Obsidian vault. You open Obsidian and find: wikilinks written as [Note Name](note-name.md) instead of [[Note Name]], broken embed syntax, incorrectly formatted callouts, YAML frontmatter placed inside the body of the file instead of at the top.

This is a real friction point. AI agents don't know Obsidian's syntax extensions, default to standard Markdown handling, and produce format-corrupted files as a result. Obsidian's internal link-tracking system depends on [[wikilink]] format — use standard Markdown links and the note falls out of the link graph entirely.

obsidian-skills is the official answer. Written by Obsidian's CEO, released January 2026, 39.3k Stars — that number signals how strongly Obsidian power users want AI agents that actually understand their vault.

What You'll Learn

What typical errors AI agents make when operating on Obsidian vaults
What each of the 5 skills teaches agents: obsidian-markdown / obsidian-bases / json-canvas / obsidian-cli / defuddle
The detailed content of the obsidian-markdown SKILL.md: complete spec for wikilinks, embeds, callouts, and Properties
Installation for Claude Code, OpenCode, and Codex
defuddle: extracting clean Markdown from web pages to save tokens

Prerequisites

Regular Obsidian user (familiar with wikilinks, callouts, and basic concepts)
Experience with Claude Code or a similar AI coding tool
Interested in having AI help manage an Obsidian knowledge base

Project Background

What Is obsidian-skills?

obsidian-skills is a set of Agent Skills for Obsidian, following the agentskills.io open standard. It allows Claude Code, Codex, OpenCode, and other skills-compatible agents to correctly handle Obsidian-specific file formats.

"Correctly handle" is the operative phrase. Obsidian adds substantial syntax extensions on top of standard CommonMark Markdown — wikilinks, embeds, callouts, Properties, inline tags. These appear rarely in training data. Agents default to standard Markdown handling and produce format-corrupted files as a result.

Author

Author: Steph Ango (GitHub: kepano) — Obsidian CEO, creator of the Minimal theme
Why the author matters: This is the spec written by the person who built the format, not a third-party approximation
License: MIT
Released: January 2026

Project Stats

⭐ GitHub Stars: 39,300+
🍴 Forks: 2,800+
📄 License: MIT

What AI Agents Get Wrong in Obsidian Vaults

Before installing obsidian-skills, here's what agents typically do with an Obsidian vault:

1. Wikilinks become standard links

# What agents write (wrong):
[Related Note](related-note.md)

# Correct Obsidian format:
[[Related Note]]

Consequence: Obsidian's bidirectional link graph breaks. When you rename the note file, the link doesn't automatically update.

2. Embed syntax breaks

# What agents write (wrong):
![image](attachment.png)

# Correct Obsidian embed syntax:
![[attachment.png]]     ← embed a file
![[Note Name]]          ← embed another note inline
![[Note#Section]]       ← embed a specific section

3. Callout format is wrong

# What agents write (wrong):
> **Note**: This is an important tip

# Correct Obsidian callout:
> [!note] Optional Title
> Callout content goes here

4. Properties/frontmatter placement errors

Properties must be the first block in the file, wrapped in triple dashes. Agents frequently insert YAML metadata mid-file, or format it incorrectly causing Obsidian parsing failures.

All 5 Official Skills

Skill 1: obsidian-markdown

Purpose: Teaches agents the complete Obsidian Flavored Markdown specification.

The SKILL.md defines a 6-step workflow:

1. Add frontmatter (Properties)
2. Write body content
3. Link related notes with wikilinks
4. Embed content with ![[...]]
5. Add callouts for important information
6. Verify formatting (ensure correct rendering)

Complete syntax coverage:

Internal Links (Wikilinks):

[[Note Name]]                   ← basic wikilink
[[Note Name|Display Text]]      ← custom display text
[[Note Name#Heading]]           ← link to specific heading
[[Note Name#^block-id]]        ← link to specific block

Embeds:

![[Note Name]]                  ← embed full note
![[image.png]]                  ← embed image
![[document.pdf#page=3]]        ← embed specific PDF page

Callouts:

> [!note] Optional Title
> Callout content

> [!warning]- Collapsed callout
> This callout is collapsed by default

> [!tip]+ Expanded callout
> This callout is expanded by default

Types: note, warning, tip, info, success, question, failure, bug, quote

Properties (YAML frontmatter):

---
tags: [tag1, tag2]
aliases: [alias1, alias2]
cssclasses: [custom-class]
created: 2026-07-02
---

Other Obsidian extensions:

Inline tags: #tag, #nested/tag
Hidden comments: %%This is hidden in Preview mode%%
Highlight: ==highlighted text==
LaTeX math: inline $formula$ , block $$formula$$
Mermaid diagrams (with Obsidian note linking support)

Key rule the skill enforces: Use [[wikilinks]] for vault-internal notes (Obsidian tracks renames automatically); use standard Markdown links only for external URLs.

Skill 2: obsidian-bases

Purpose: Teaches agents to create and edit .base files — Obsidian's native database view format.

.base files let you query and display vault notes as a database:

Coverage:
- Creating and editing views (table view, gallery view, etc.)
- Setting filter conditions (by tags, dates, Properties fields)
- Defining formulas (spreadsheet-like calculations)
- Configuring summaries (aggregate statistics)

This is a relatively new Obsidian feature (native database views) with almost no coverage in agent training data. The skill is currently one of the most authoritative format specifications available.

Skill 3: json-canvas

Purpose: Teaches agents to create and edit .canvas files — Obsidian's whiteboard format, also the JSON Canvas open standard.

{
  "nodes": [
    {"id": "node1", "type": "text", "text": "Idea A", "x": 0, "y": 0, "width": 200, "height": 100},
    {"id": "node2", "type": "file", "file": "Related Note.md", "x": 300, "y": 0, "width": 200, "height": 100}
  ],
  "edges": [
    {"id": "edge1", "fromNode": "node1", "toNode": "node2"}
  ]
}

Agents can create complex mind maps and knowledge visualizations programmatically rather than through GUI drag-and-drop.

Skill 4: obsidian-cli

Purpose: Teaches agents to interact with Obsidian vaults via command line and develop plugins and themes.

Covers:

Batch file operations in the vault
Obsidian URI protocol for triggering operations
Plugin development directory structure and API conventions
Theme development CSS variables and specifications

Skill 5: defuddle

Purpose: Extract clean Markdown content from web pages, removing ads, navigation, and sidebars — specifically designed to save tokens.

Input: A URL or raw HTML (contains ads, nav menus, sidebars)
Output: Clean Markdown body content

Use cases:
  "Save this article to my vault"
  → Agent uses defuddle to extract clean content
  → Generates a correctly formatted Obsidian note
  → Doesn't stuff the full noisy HTML into context

Defuddle is also an independent open-source project (kepano/defuddle). The skill in obsidian-skills teaches agents how to invoke it.

Deep Dive

Why 39.3k Stars for Five Markdown Files

That number for what is essentially five SKILL.md files signals several things:

Obsidian's user demographics: Obsidian's core users are enthusiastic about knowledge management and tool integration, and among the earliest adopters of AI agent workflows.

A real pain point: AI agents corrupting Obsidian vault formatting had been a community frustration for a long time. The official answer spread quickly.

Author credibility: Written by Obsidian's CEO means the format specifications are authoritative, not community-approximated. Every nuance is intentional.

Installation

Claude Code (recommended):

Place the repository contents in a /.claude folder at the vault root:

# Navigate to your Obsidian vault root
cd /path/to/your/vault

# Clone into .claude directory
git clone https://github.com/kepano/obsidian-skills .claude/skills/obsidian-skills

Or with npx:

npx skills add https://github.com/kepano/obsidian-skills

OpenCode:

git clone https://github.com/kepano/obsidian-skills.git ~/.opencode/skills/obsidian-skills

Important: clone the full repository, not just the inner skills/ directory. The path needs to resolve as ~/.opencode/skills/obsidian-skills/skills/<skill-name>/SKILL.md.

Marketplace (in supported agents):

/plugin marketplace add kepano/obsidian-skills

Skill Auto-Activation

After installation, agents don't need to be told which skill to use. When the task involves Obsidian file operations, the relevant skill loads automatically:

You say: "Create today's daily note in vault/daily-notes/,
         with today's todos and meeting notes, linking to relevant project notes"

Agent detects Obsidian file operation
    ↓
Automatically loads obsidian-markdown SKILL.md
    ↓
Generates according to skill spec:
  - YYYY-MM-DD.md filename
  - Properties frontmatter with tags and date fields
  - [[Project Note Name]] wikilink format
  - Correctly formatted callouts for important items

Relationship to the Agent Skills Ecosystem

obsidian-skills follows the agentskills.io open standard — the same format used by android/skills (Google's official Android dev skills), agent-skills (Addy Osmani's engineering discipline skills), and others.

This means:

The same skill files work across Claude Code, Codex, and OpenCode without modification
Any new tool supporting the Agent Skills standard works immediately

Real Use Cases

Use case 1: Research archiving

"Save the content of this URL to vault/research/,
 extract key points, mark them with callouts,
 and link to related existing notes"

→ Agent uses defuddle to extract clean Markdown
→ Uses obsidian-markdown spec to generate correctly formatted note
→ Automatically creates wikilinks to related notes

Use case 2: Knowledge visualization

"Scan my vault notes on machine learning,
 create a .canvas mind map visualizing their relationships"

→ Agent uses obsidian-cli to read vault content
→ Uses json-canvas spec to generate .canvas file
→ Nodes and edges in correct format

Use case 3: Format migration

"Convert all [Note Name](note.md) style links in my vault
 to Obsidian [[Note Name]] wikilink format"

→ Agent knows the correct wikilink syntax
→ Batch modification won't damage other link types
→ External URLs remain untouched

Links and Resources

🌟 GitHub: kepano/obsidian-skills
🌐 Obsidian: obsidian.md
🔧 Defuddle: kepano/defuddle
📖 JSON Canvas standard: jsoncanvas.org
🌐 Agent Skills standard: agentskills.io

Conclusion

obsidian-skills has value at two levels.

At the surface: it fixes the specific problem of AI agents corrupting Obsidian formatting. Five skill files teach agents to use wikilinks, embeds, callouts, and Properties correctly. Your vault stops getting polluted by format-broken files written by AI.

At a deeper level: this is a signal from Obsidian's CEO that tools like Obsidian are beginning to treat AI agents as first-class citizens. Personal knowledge bases are evolving into infrastructure that agents can read and write, not just places you type into.

For heavy Obsidian users, this skill is close to essential. It transforms Claude Code from "a tool that might break your vault formatting" into "an assistant that can genuinely help manage your second brain."

Explore PrimeSkills — A marketplace for handpicked AI Agents and skills. Each is validated in real enterprise workflows, stripping away hype and keeping only what truly works.

Welcome to my Homepage for more useful insights and interesting products.

Workflow Series (03): State Management — Persistence, Idempotency, and Version Binding

WonderLab — Wed, 01 Jul 2026 02:27:59 +0000

Why State Management Is the Core Problem

An Agent Workflow crashes at Phase 5. After restart, does it begin from the top or continue from Phase 6?

Without state persistence, it starts over: every LLM call, tool execution, and human approval is discarded.

State management means the workflow resumes from the last checkpoint regardless of when interruption occurs. It's also the mechanism behind human approval gates — a triggered gate pauses the workflow at a specific state, and the human response resumes from exactly that state.

Durable Execution Pattern

Serialize execution as recoverable checkpoints. Any interruption resumes from the most recent one with results identical to uninterrupted execution. Temporal.io implements this at the code layer, but the same semantics work with a JSON file.

State File Structure

{
  "workflow_id": "wf-bug-e2e-AE-33995-20260601",
  "workflow_version": "1.3.0",
  "jira_key": "AE-33995",
  "started_at": "2026-06-01T10:00:00+08:00",
  "phase": "phase_4",
  "phases": {
    "phase_1": {
      "status": "done",
      "completed_at": "2026-06-01T10:02:30+08:00",
      "output_file": "bug_info.json"
    },
    "phase_4": {
      "status": "in_progress",
      "step": "step_4_1",
      "steps": {
        "step_4_1": {"status": "done", "output_file": "candidate_a.json"},
        "step_4_2": {"status": "in_progress"},
        "step_4_3": {"status": "pending"}
      }
    }
  }
}

Resume Protocol

def resume_workflow(state_file: Path) -> None:
    state = json.loads(state_file.read_text())

    for phase_id, phase_data in state["phases"].items():
        if phase_data["status"] == "done":
            continue  # skip completed phases

        if phase_data["status"] in ("in_progress", "pending"):
            # in_progress treated same as pending — re-execute
            # (idempotency guarantees this is safe)
            execute_phase(phase_id, state)
            return

The key principle: trust only the state file, not memory. The main Agent doesn't remember what it did — it reads the status field. Phases marked in_progress get re-executed, which requires every phase operation to be idempotent.

Double-Ended Writes

Write to the state file both before a phase starts and after it completes — not only on completion:

def execute_phase(phase_id: str, state: dict) -> None:
    # Before start: mark in_progress
    # (if crash occurs, resume finds this phase and re-executes it)
    state["phases"][phase_id]["status"] = "in_progress"
    write_state(state)

    try:
        result = run_phase_logic(phase_id, state)

        # After completion: mark done, record output file path
        state["phases"][phase_id]["status"] = "done"
        state["phases"][phase_id]["output_file"] = result.output_file
        write_state(state)

    except Exception as e:
        state["phases"][phase_id]["status"] = "failed"
        state["phases"][phase_id]["error"] = str(e)
        write_state(state)
        raise

Idempotency Design

The resume protocol re-executes in_progress phases, meaning a phase can run twice. Operations that aren't idempotent produce duplicate side effects: two Jira comments, two git commits, two notification emails.

Idempotency Analysis by Operation Type

File writes (naturally idempotent)

# Overwrite is idempotent — running twice produces the same result
output_file.write_text(json.dumps(result))  # ✅

Jira comments (not idempotent — requires detection)

# ❌ Wrong: direct write produces a duplicate comment on re-run
jira.add_comment(issue_key, comment_text)

# ✅ Correct: check for existing comment with this run's ID first
def add_comment_idempotent(issue_key: str, comment_text: str, run_id: str) -> None:
    existing = jira.get_comments(issue_key)
    marker = f"[run_id:{run_id}]"  # unique marker per workflow run

    if any(marker in c.body for c in existing):
        return  # already written — skip

    jira.add_comment(issue_key, f"{marker}\n{comment_text}")

Git commits (not idempotent — requires detection)

# ❌ Wrong: direct commit creates a second commit on re-run
git.commit(message)

# ✅ Correct: check if commit result file exists and passed=true
def commit_idempotent(message: str, output_file: Path) -> dict:
    if output_file.exists():
        result = json.loads(output_file.read_text())
        if result.get("passed"):
            return result  # already committed successfully

    commit_sha = git.commit(message)
    result = {"passed": True, "sha": commit_sha}
    output_file.write_text(json.dumps(result))
    return result

External API triggers (conditionally idempotent)

# Adding a Gerrit reviewer: duplicate adds don't error — naturally idempotent ✅
gerrit.add_reviewer(change_id, reviewer)

# Creating a cron job: duplicate creates produce two jobs ❌
# Fix: list first, create only if not already present
def create_cron_idempotent(job_config: dict) -> None:
    existing_jobs = cron.list_jobs()
    if any(j["name"] == job_config["name"] for j in existing_jobs):
        return  # already exists — skip
    cron.create_job(job_config)

Idempotency Self-Check

For every new Step, answer these three questions before implementing:

□ If this step runs twice, does it produce side effects?
□ If yes, how do you detect "already executed" and skip?
□ Is the detection logic itself idempotent?

The third question is easy to miss. If detection depends on in-memory state or has side effects of its own, it fails in the resume scenario just like the original operation.

State File Version Binding

Modify a workflow definition mid-run — add a new Step, for example — and the old state file has no record of it. When the workflow resumes, the main Agent has no basis for handling the missing step.

The fix: bind the workflow version in the state file and verify it on resume.

def start_or_resume(state_file: Path, current_version: str) -> dict:
    if state_file.exists():
        state = json.loads(state_file.read_text())
        saved_version = state.get("workflow_version")

        if saved_version != current_version:
            raise WorkflowVersionMismatch(
                f"State file version: {saved_version}\n"
                f"Current workflow version: {current_version}\n"
                f"Options:\n"
                f"  1. Resume with saved state using old workflow ({saved_version})\n"
                f"  2. Start fresh with new workflow ({current_version})\n"
                f"  3. Manually migrate the state file"
            )

        return state  # versions match — resume normally

    # New run: create state file
    state = {
        "workflow_version": current_version,
        "started_at": datetime.now(timezone.utc).isoformat(),
        "phases": {}
    }
    write_state(state, state_file)
    return state

Version Number Rules (MAJOR.MINOR.PATCH)

MAJOR: Phase structure changes (add/remove Phase, major routing changes)
        → Breaks in-progress runs; requires explicit handling
        → Cannot resume directly; user must decide

MINOR: Add Step, template improvements, new gate options
        → Backward compatible; in-progress runs complete with old version
        → New runs use new version

PATCH: Wording tweaks, config adjustments, behavior unchanged
        → Safe to upgrade; old state files resume without issue

Design Checklist

State persistence

[ ] Every Phase/Step writes in_progress before starting and done after completing
[ ] Resume protocol reads only the state file, not conversation history
[ ] State file includes workflow_version

Idempotency

[ ] All external writes (Jira comments, git commits, API calls) have idempotency checks
[ ] Detection uses a unique identifier (run_id or output file existence)
[ ] The detection logic itself produces no side effects

Version binding

[ ] Version is verified on resume against the current workflow version
[ ] MAJOR version changes have an explicit handling strategy
[ ] Version mismatches surface user-actionable options, not just an error exit

Summary

Durable Execution requires double-ended writes: write in_progress before the phase starts and done after — a crash at any point allows precise resumption
Resume requires idempotency: in_progress phases get re-executed, so every external write must be safe to run twice; file writes are naturally idempotent, Jira comments and git commits need explicit detection
Version binding prevents silent errors: when a workflow is modified, a mismatch between the old state file and the new workflow version should surface actionable options — not silently apply new logic to old state

Check out PrimeSkills — a curated marketplace of AI agents and skills that have been validated in real-world, enterprise-grade workflows. No fluff, just what actually works.

Find more useful knowledge and interesting products on my Homepage

Open Source Project of the Day (#111): HyperGraphRAG — N-ary Relations via Hyperedges, the Third-Generation RAG Paradigm

WonderLab — Wed, 01 Jul 2026 02:26:32 +0000

Introduction

"Every edge in a knowledge graph connects exactly two nodes — but real-world facts routinely involve three, four, or more entities simultaneously."

This is article #111 in the Open Source Project of the Day series. Today's project is HyperGraphRAG — the official implementation of the NeurIPS 2025 paper "Retrieval-Augmented Generation via Hypergraph-Structured Knowledge Representation."

RAG technology has a clear evolutionary trajectory:

1st generation (Naive RAG): Chunk documents, retrieve by vector similarity
2nd generation (GraphRAG / LightRAG): Extract knowledge graphs, use graph structure for retrieval
3rd generation (HyperGraphRAG): Replace knowledge graphs with hypergraphs, represent N-ary relations via hyperedges

This article explains the core question: what limits knowledge graph binary edges, how hypergraph hyperedges address that limitation, and what the change produces in actual RAG performance.

What You'll Learn

The fundamental difference between hypergraphs and knowledge graphs: why binary edges lose information when representing N-ary facts
HyperGraphRAG's three-phase pipeline: knowledge hypergraph construction → retrieval → generation
Benchmark results across medicine, agriculture, CS, and law
Comparison with GraphRAG, LightRAG, and Naive RAG
Implementation and quick start

Prerequisites

Familiarity with RAG (Retrieval-Augmented Generation) concepts
Basic understanding of knowledge graphs (nodes, edges, triples)
Python basics

Project Background

What Is HyperGraphRAG?

HyperGraphRAG is the first hypergraph-structured RAG system, published at NeurIPS 2025. It replaces knowledge graph binary edges (connecting exactly two nodes) with hyperedges (connecting any number of nodes simultaneously), natively representing multi-entity relationships in real-world facts.

Author / Team

First author: Haoran Luo (haoran.luo@ieee.org)
Published: NeurIPS 2025 (Advances in Neural Information Processing Systems, vol. 38, pp. 152206–152234)
arXiv: 2503.21322
License: MIT

Project Stats

⭐ GitHub Stars: 415+
🔬 Published at: NeurIPS 2025
📄 License: MIT
🐍 Language: Python 100%

Core Concept: Hypergraph vs. Knowledge Graph

Before the pipeline details, the core concept needs to be clear.

The Limitation of Knowledge Graphs: Binary Edges

Traditional knowledge graphs represent facts as triples: (subject, relation, object). Every edge connects exactly two nodes.

Knowledge graph representation:
Alice  ─[co-author]─→  paper_X
Bob    ─[co-author]─→  paper_X
Carol  ─[co-author]─→  paper_X
paper_X ─[published_at]─→ NeurIPS
paper_X ─[year]─→ 2025

5 separate binary edges, 5 extraction steps, the relationship is fragmented

This representation has a fundamental information loss: "Alice, Bob, and Carol jointly co-authored paper X" as a single fact has been decomposed into five isolated edges. Retrieval that finds only two or three of them struggles to reconstruct the complete relationship.

How Hypergraphs Solve This: Hyperedges

A hypergraph allows one edge (hyperedge) to connect any number of nodes, directly representing N-ary facts:

Hypergraph representation:
{Alice, Bob, Carol, paper_X, NeurIPS, 2025}
     ────────────[co-authored]────────────→
         One hyperedge, complete N-ary relationship preserved

A hyperedge packages all entities involved in a fact together, with no decomposition needed. Retrieving one hyperedge delivers the complete relational context.

More concrete comparison:

Event: A meeting
  Attendees: Alice, Bob, Carol
  Date: 2025-06-15
  Location: Beijing
  Topic: Product roadmap discussion

Knowledge graph:
  (Alice, attended, meeting_001)
  (Bob, attended, meeting_001)
  (Carol, attended, meeting_001)
  (meeting_001, date, 2025-06-15)
  (meeting_001, location, Beijing)
  (meeting_001, topic, product_roadmap_discussion)
  ← 6 edges, relationship broken apart

Hypergraph:
  Hyperedge: {Alice, Bob, Carol, 2025-06-15, Beijing, product_roadmap_discussion}
  Relation: co-attended-meeting
  ← 1 hyperedge, N-ary relationship intact

System Architecture: Three-Phase Pipeline

Phase 1: Knowledge Hypergraph Construction (Indexing)

from hypergraphrag import HyperGraphRAG

rag = HyperGraphRAG(working_dir="expr/my_project")

# Insert documents, triggers knowledge hypergraph construction
rag.insert(documents)

Construction process:

Document chunking: Split input documents into chunks
N-ary fact extraction: Use LLM to extract N-ary relational facts from each chunk
- Not just (subject, relation, object) triples
- Extract complete facts involving N entities simultaneously
Hyperedge construction: Convert each N-ary fact into a hyperedge
- Each hyperedge contains: all related entity nodes + relation type + provenance
Hypergraph storage: Persist the node set and hyperedge set to the working directory

Phase 2: Hypergraph Retrieval

result = rag.query("What papers did Alice and Bob co-author in 2025?")

The key difference between hypergraph retrieval and knowledge graph retrieval:

Knowledge graph retrieval:
  Find Alice node
  → Find all binary edges connecting Alice
  → Find edges containing Bob
  → Take intersection
  → Multi-hop path reasoning, easy to miss connections

Hypergraph retrieval:
  Find Alice node
  → Find all hyperedges containing Alice
  → Hyperedges already contain Bob, papers, dates as complete context
  → Directly locate relevant hyperedges, no multi-hop reasoning needed

Phase 3: Generation

Retrieved hyperedge content serves as context for the LLM:

Retrieved context (hyperedge):
  Entities: {Alice, Bob, paper_X, NeurIPS, 2025}
  Relation: co-authored
  Summary: Alice and Bob co-authored paper_X, published at NeurIPS 2025,
           on the topic of hypergraph-structured knowledge representation

The LLM receives complete, structured N-ary relationship context —
not fragments assembled from multiple disconnected binary edges

Benchmark Results

The paper evaluates across four domain datasets, comparing against Naive RAG, GraphRAG, and LightRAG:

Domains: Medicine, Agriculture, Computer Science, Law

Metrics: Answer accuracy, retrieval efficiency, generation quality

Finding: HyperGraphRAG outperforms across all four domains:

vs. Naive RAG (vector retrieval): better multi-entity relationship understanding
vs. GraphRAG: less information loss from binary decomposition
vs. LightRAG: significant improvement on complex N-ary relationship scenarios

The domain selection is deliberate:

Medicine: Drug interactions involving multiple simultaneous medications are N-ary by nature — "A interacts with B" doesn't capture polypharmacy
Law: Contract clauses involving multiple parties, facts constrained by multiple statutes simultaneously
Computer Science: Technical facts linking algorithms, data structures, applications, and performance constraints
Agriculture: Crop growth conditions where soil, climate, fertilizer, and pests interact simultaneously

The RAG Paradigm Evolution

1st generation: Naive RAG
  Documents → Embeddings → Vector database
  Query → Similarity search → Return chunks
  Problem: Semantic retrieval, no structural knowledge

2nd generation: GraphRAG (Microsoft) / LightRAG (HKUDS)
  Documents → Extract knowledge graph (triples) → Graph database
  Query → Graph traversal → Structured context
  Problem: Binary edges can't natively represent N-ary relations; complex facts get fragmented

3rd generation: HyperGraphRAG (NeurIPS 2025)
  Documents → Extract N-ary facts → Hypergraph (hyperedges)
  Query → Hyperedge retrieval → Complete N-ary relationship context
  Advantage: Relationship integrity preserved; less noise accumulation in multi-hop reasoning

This evolution has an underlying logic: real-world knowledge isn't binary. A paper's authorship involves multiple authors, institutions, and dates. A legal judgment involves plaintiff, defendant, judge, statutes, and facts. A business contract involves multiple parties, multiple clauses, and multiple milestone dates.

Forcing all of this into binary edges is an architectural mismatch between the representation and the knowledge it encodes.

Quick Start

Setup:

git clone https://github.com/LHRLAB/HyperGraphRAG
cd HyperGraphRAG

conda create -n hypergraphrag python=3.11
conda activate hypergraphrag

pip install -r requirements.txt

Configure OpenAI API:

export OPENAI_API_KEY=your_key

Basic usage:

from hypergraphrag import HyperGraphRAG
import asyncio

async def main():
    rag = HyperGraphRAG(working_dir="expr/test")

    # Build hypergraph index
    with open("your_document.txt", "r") as f:
        content = f.read()
    await rag.ainsert(content)

    # Query
    result = await rag.aquery("Your question here")
    print(result)

asyncio.run(main())

Limitations and When to Use It

Well-suited for:

Documents with dense multi-entity relationships (medical records, legal documents, academic papers)
Queries requiring complex reasoning across multiple entities
Scenarios where GraphRAG has hit a ceiling on relation retrieval accuracy

Worth considering:

Hypergraph construction is more complex than standard KG extraction — LLM needs to identify N-ary facts, which costs more in time and API calls
Currently requires OpenAI API (extensible to other LLMs)
Research code, not a production framework — the README describes this as a research implementation

Links and Resources

🌟 GitHub: LHRLAB/HyperGraphRAG
📄 arXiv paper: 2503.21322
🔬 NeurIPS 2025: neurips.cc/virtual/2025/poster/115764
📧 Contact: haoran.luo@ieee.org

Conclusion

HyperGraphRAG's contribution in one sentence: replacing binary edges with hyperedges lets RAG systems natively represent N-ary relationships.

That sounds like a graph structure implementation detail — but for document corpora full of multi-entity relationships, it addresses a fundamental information compression problem. When GraphRAG decomposes N-ary facts into multiple binary edges, the holistic relationship is already lost. All subsequent retrieval and reasoning operate on incomplete information.

NeurIPS 2025 publication signals academic validation of this direction. For developers using GraphRAG or LightRAG who are hitting accuracy ceilings on complex relational queries, this is a research direction worth understanding and experimenting with.

Explore PrimeSkills — A marketplace for handpicked AI Agents and skills. Each is validated in real enterprise workflows, stripping away hype and keeping only what truly works.

Welcome to my Homepage for more useful insights and interesting products.

Open Source Project of the Day (#110): openpilot — The Open-Source Driver Assistance System That Beat Tesla Autopilot in Consumer Reports

WonderLab — Tue, 30 Jun 2026 02:52:19 +0000

Introduction

"openpilot is an operating system for robotics. Currently, it upgrades the driver assistance system on 325+ supported cars."

This is article #110 in the Open Source Project of the Day series. Today's project is openpilot — comma.ai's open-source semi-automated driving software, one of the most-starred autonomous driving repositories on GitHub.

In 2020, Consumer Reports published a driver assistance system evaluation. The top-ranked system wasn't Tesla Autopilot, wasn't Cadillac Super Cruise — it was open-source software running on a third-party device you plug in yourself.

In April 2024, an ordinary 2017 Toyota Prius, with a comma 3X device, completed a coast-to-coast US drive at 98.4% autonomy in 43 hours 18 minutes — beating Tesla Model S's previous record by nearly 12 hours.

This is not a demo project. 62.8k Stars, running in 10,000+ users' real vehicles, over 100 million miles accumulated.

What You'll Learn

openpilot's technical architecture: why end-to-end neural networks instead of separate perception and planning modules
The panda safety architecture: how ISO 26262 safety levels are achieved in open-source software
The World Model in 0.11: training real-world driving policy inside a learned simulated world
George Hotz and comma.ai's origin story
openpilot vs. Tesla Autopilot in context
How to contribute (including comma.ai's bounty program)

Prerequisites

Familiarity with driver assistance systems (ADAS) basics
Basic understanding of neural networks
Background in automotive electronics (CAN bus) is helpful but not required

Project Background

What Is openpilot?

openpilot is an open-source semi-automated driving system that uses an end-to-end neural network to predict driving trajectory directly from camera images — no separate perception module, no separate planning module, just a unified network from pixels to control commands.

It connects to the car's CAN bus through comma four hardware, replaces the stock driver assistance system, and provides better lane centering, adaptive cruise control, and driver monitoring than the factory system.

Author / Company

Founder: George Hotz (geohot) — the first person to unlock an iPhone, the first to crack PS3 encryption
Company: comma.ai (founded September 2015)
Open-sourced: November 30, 2016
License: MIT

Project Stats

⭐ GitHub Stars: 62,800+
🍴 Forks: 11,100+
🚗 Supported vehicles: 325+
📍 Accumulated miles: 100M+
👥 Active users: 10,000+

Core Features

What openpilot Does

After installing the comma four device and connecting it to a supported car:

Automated Lane Centering (ALC): Replaces the factory lane keeping assist. Uses the neural network to keep the car centered in the lane. Handles faded lane markings, construction zones, varied road conditions.

Adaptive Cruise Control (ACC): Detects vehicles ahead, automatically controls acceleration and braking to maintain safe following distance. Integrates OpenStreetMap for automatic speed adjustment on curves.

Lane Change Assist: Assists lane changes after turn signal activation, with blind spot awareness.

Driver Monitoring: Camera-based alertness tracking. Alerts after approximately 6 seconds of detected distraction, without the constant steering wheel nagging many factory systems use.

Factory safety features preserved: Automatic Emergency Braking (AEB), blind spot warning, auto high beams — all kept as-is from the factory.

Supported Brands and Models

Primary support: Toyota, Hyundai, Honda, Ford, plus GM, Subaru, Nissan, and others — 325+ specific models total. Full list in CARS.md.

Required Hardware

comma four device: $999. Three cameras for 360° vision, Qualcomm Snapdragon 845 processor, 4G LTE + WiFi, OLED display, CAN FD enabled, high-precision GPS.
Car harness: The cable connecting comma four to the car's CAN network.

Technical Architecture

End-to-End Neural Network

openpilot's most important architectural decision is the end-to-end approach: camera images in, control commands out. No separate perception layer, no separate planning layer — one unified network trained directly on driving data.

Traditional ADAS architecture:
Camera → [Perception module] → [Object detection] → [Path planning] → [Control]
Each module designed separately; errors compound across layers

openpilot end-to-end:
Camera → [Unified neural network] → Control commands
One model, trained end-to-end, from pixels to steering angle

The end-to-end advantage: no hand-engineered features needed. The model learns to handle faded lane lines, international road markings, weather variations — because it's trained on millions of real-world driving miles that contain all of those situations.

openpilot 0.11: World Model Training

openpilot 0.11 shipped a new driving model codenamed WMI (🍉). The core innovation: training a driving policy inside a learned simulated world — claimed as the first deployment of this approach for real-world robotics shipped to users.

Two-stage training:

Stage 1: Train the World Model
  Input: Unlabeled fleet driving data (video)
  Architecture: 2B-parameter diffusion Transformer
  Outcome: A world simulator that predicts "what happens next"
  (The neural network builds an internal model of the driving world)

Stage 2: Train the driving policy
  Environment: Interactions with the World Model (not the real world)
  Training: Small driving policy network interacts with the World Model
  Outcome: A policy that learned to drive inside the simulated world

World Model technical specs:

ViT encoder (50M parameters) + decoder (100M parameters)
Diffusion Transformer: 2B parameters, trained on 2.5M minutes of video
Throughput: 12.2 frames/sec/GPU

Power efficiency improvement: Idle power consumption dropped from 225 mW to 52 mW when parked — a 77% reduction via peripheral disabling, voltage scaling, and deep stop mode.

panda: The Safety Architecture

openpilot sends control commands to a car. That makes safety the core engineering problem. All safety-critical code lives in the separate panda module:

Written in C (Python is faster to develop but carries GC pauses and runtime risk)
Follows ISO 26262 functional safety standards
Safety rules enforced in hardware: steering torque limits, speed limits, emergency takeover logic
panda runs on a separate processor inside the comma four, isolated from the main openpilot software

This design means: even if openpilot's main software has a bug or is compromised, the hardware safety layer in panda remains effective.

Testing Infrastructure

Software-in-the-loop tests (every commit)
  └── Simulated driving scenarios, regression suite

Hardware-in-the-loop tests (internal Jenkins)
  └── Software running on actual comma hardware

Physical replay testing (runs continuously)
  └── "A testing closet containing 10 comma devices
       continuously replaying routes, detecting behavior changes"

This testing stack is unusually thorough for open-source automotive software.

Historical Milestones

Date	Event
Sept 2015	George Hotz founds comma.ai
2016	Demo on Acura ILX; California DMV cease-and-desist
Nov 2016	openpilot open-sourced
Nov 2020	Consumer Reports ranks openpilot #1 above Tesla Autopilot
2021	comma three released at $2,199
2023	comma 3X released at $1,250
April 2024	US coast-to-coast in 43h18m at 98.4% autonomy, breaks record
2025	comma four released at $999, three-camera design
2026	openpilot 0.11, World Model-trained driving policy

What the Consumer Reports 2020 Ranking Means

Consumer Reports evaluated lane-centering accuracy, safety, usability, and abuse prevention. openpilot scored first not because of hardware advantages — it's a third-party plug-in device running open-source software — but because of the software's algorithm quality. A system built on consumer hardware and open-source code outperformed Tesla, Cadillac, and Ford factory systems.

The 2024 Coast-to-Coast Record

A stock 2017 Toyota Prius. $999 comma 3X device. No special route planning. 98.4% autonomy across the continental US. Beating Tesla Model S's prior record by nearly 12 hours doesn't describe technical specifics, but it illustrates the calibration between the system's capability and real-world conditions.

Ecosystem

Community Forks

11,000+ forks on GitHub. The community maintains extended versions with:

Traffic light and stop sign detection
Parking lot navigation
Pre-Autopilot Tesla support
Custom driving behavior parameters

Contributor Bounties

comma.ai operates a bounty system paying external contributors for adding new car support and fixing bugs. Cash incentives for open-source automotive software contributions are rare.

tinygrad

comma.ai simultaneously maintains tinygrad — a minimalist deep learning framework serving as openpilot's neural network inference backend. openpilot's training and inference code is migrating to tinygrad.

Links and Resources

🌟 GitHub: commaai/openpilot
🌐 Website: comma.ai
📖 Docs: docs.comma.ai
🚗 Supported vehicles: docs.comma.ai/vehicles
💬 Community: discord.comma.ai
🔧 tinygrad: github.com/tinygrad/tinygrad

Safety Disclaimer

The MIT license includes this notice:

"THIS IS ALPHA QUALITY SOFTWARE FOR RESEARCH PURPOSES ONLY. THIS IS NOT A PRODUCT."

openpilot is a driver assistance system, not fully autonomous driving. Drivers must remain alert at all times and be ready to take over immediately.

Conclusion

openpilot is one of the few large open-source projects running in genuinely safety-critical environments. The 62.8k Stars represent 10,000+ users' real driving miles, not notebook experiments.

The end-to-end neural network architecture was an aggressive choice in 2016. It's now becoming the industry standard — Tesla FSD moved to end-to-end too. openpilot was one of the earliest large-scale validations of that approach.

The World Model-based training in 0.11 — training driving policy in a learned simulated world rather than a hand-crafted simulator — represents a direction the research community has discussed for years. openpilot deployed it to real users' cars.

In a field that traditionally requires billion-dollar investments and closed ecosystems, George Hotz built a parallel path using open-source software and consumer hardware. That path beat factory systems from the world's largest automakers in a Consumer Reports evaluation. The approach itself is worth studying.

Explore PrimeSkills — A marketplace for handpicked AI Agents and skills. Each is validated in real enterprise workflows, stripping away hype and keeping only what truly works.

Welcome to my Homepage for more useful insights and interesting products.

Workflow Series (02): Design Patterns — Four-Layer Architecture, Three Context Modes, and Approval Gate Design

WonderLab — Mon, 29 Jun 2026 02:56:14 +0000

From Script to Engineering

An early-stage workflow is often a single file: one Markdown that describes everything, with all configuration hardcoded. This works at small scale. As the workflow grows, three problems appear:

Changing a timeout requires finding and updating multiple locations
Subagent task prompts are scattered through the workflow definition, impossible to test independently
Security policy and business logic are mixed together, making compliance review painful

The four-layer architecture addresses all three.

Four-Layer Architecture

Policy Layer     policy.md         Execution rules, global constraints
                                    → Who can do what; authorization for high-risk ops

Workflow Layer   workflow.md        Phase / Step structure, routing logic
                                    → The skeleton; no specific task content

TaskSpec Layer   templates/         Subagent task prompt templates
                                    → Detailed instructions and output contracts per task

Tool/Skill Layer skills/            Atomic capabilities
                                    → Skill definitions reusable across workflows

Core principle: each layer changes only its own concerns — nothing crosses layers.

# ✅ Correct: change analysis timeout → edit workflow.md
phase_3_analyze:
  timeout: 30m  ← Workflow Layer change

# ✅ Correct: change analysis output format → edit templates/analyze.md
## Output Contract
{"confidence": float, "root_cause": str, ...}  ← TaskSpec Layer change

# ❌ Wrong: write permission rules inside a task prompt (permissions belong in Policy Layer)
# ❌ Wrong: write specific analysis steps inside workflow.md (steps belong in TaskSpec Layer)

Layer separation makes changes safe: editing templates/ only affects the corresponding subagent's output. Editing policy.md cannot accidentally break routing logic.

Context Passing Modes

Deciding what a subagent should know is where workflow design goes wrong most often.

Passing the main Agent's full history to every subagent is the most common mistake. Context explodes: subagents slow down, output quality drops, token cost doubles.

Choose a passing mode based on what the subagent actually needs. Three modes:

accumulate

Definition: pass all relevant outputs the workflow has produced so far.

When to use: the subagent synthesizes conclusions from multiple earlier phases.

# Phase 7: write closing notification, needs conclusions from the whole workflow
phase_7_notify:
  context_mode: accumulate
  context_inputs:
    - phases.phase3.root_cause_summary
    - phases.phase4.fix_summary
    - phases.phase5.commit_result
    - phases.phase6.review_status

The Phase 7 subagent needs root cause, fix summary, commit outcome, and review status. Missing any one of them produces an incomplete notification.

last_only

Definition: pass only the output of the immediately preceding phase or step.

When to use: the subagent's task depends entirely on its direct predecessor; history is irrelevant.

# Phase 2: extract log files — only needs the attachment path from Phase 1
phase_2_extract_logs:
  context_mode: last_only
  context_inputs:
    - phases.phase1.attachment_path   # one field is all it needs

Extracting logs doesn't need the full Jira ticket details — just where the file is. Passing all of Phase 1's output wastes context. last_only enforces taking only what's needed.

explicit

Definition: name every specific field the subagent needs, sourcing from any prior phase.

When to use: the subagent needs specific fields from multiple phases, but not the complete output of any single phase.

# Phase 3: root cause analysis — needs bug_info (Phase 1) + log_dir (Phase 2)
phase_3_analyze:
  context_mode: explicit
  context_inputs:
    - source: phases.phase1
      fields: [bug_info.summary, bug_info.stack_trace, bug_info.jira_key]
    - source: phases.phase2
      fields: [log_dir, extracted_files]

Phase 3 needs the bug description (from Phase 1) and the log directory (from Phase 2), but not Phase 1's attachment path or Phase 2's raw extraction log. explicit mode controls precisely what flows into the subagent.

Choosing a Mode

Subagent synthesizes conclusions from multiple phases  → accumulate
Subagent depends only on its direct predecessor        → last_only
Subagent needs specific fields from multiple sources   → explicit (recommended default)

explicit is the safest default. Even when you're unsure what a subagent needs, start by naming specific fields. It's easier to debug than over-passing, and it documents the data dependencies explicitly.

Approval Gate Design

Approval gates are the nodes where humans intervene. Incomplete gate definitions are a common source of production incidents.

Three Gate Types

interrupt (blocking)
  Workflow pauses completely until human responds
  For: high-risk operations (code merge, production deploy)

notification (non-blocking)
  Workflow continues; human is notified in parallel
  For: low-risk operations where awareness is enough

approval (async)
  Asynchronous wait for approval within a specified time window
  For: formal approval processes with SLA requirements

Five Required Fields

# Complete approval gate definition
- gate_id: gate_B
  type: interrupt
  trigger_condition: "fix_result.all_passed == false after 3 retries"
  message: |
    Fix attempts: 3 failures.
    Root cause: {{ phases.phase3.root_cause_summary }}
    Last error: {{ phases.phase4.last_error }}

    Choose next action:
  options:
    - label: Manual intervention
      value: manual_fix
    - label: Re-analyze root cause
      value: re_analyze
    - label: Mark as requires manual fix
      value: mark_manual
  timeout: 24h
  timeout_action: pause    # ← most commonly omitted field

timeout_action is the most frequently missing field. Options:

pause    → suspend workflow after timeout, wait for human to resume (most common)
continue → proceed with default option after timeout (low-risk notification gates)
abort    → terminate the entire workflow after timeout (strict time-window operations)

A gate without timeout_action leaves the workflow hanging indefinitely: no alert fires, no record is written, no recovery path exists.

Approval Gate Message Design

The gate message is read by humans. It directly determines how fast decisions get made.

✅ Effective gate message:
  "Test pass rate: 67% (8/12 passing)
   Failing tests: test_null_input, test_overflow
   Current fix: modified boundary check in parseInput()
   Recommended action: re-analyze root cause — failure pattern
   doesn't match the identified root cause"

❌ Ineffective gate message:
  "Fix failed. Choose an action."

A good message lets the reviewer decide in 30 seconds. A bad one sends them to the logs.

Serial Retry vs Parallel Candidates

When a workflow encounters failure, two response strategies exist. Choosing the wrong one degrades efficiency or quality.

Serial Retry

Attempt 1 → fail
           ↓ (with failure reason + feedback)
Attempt 2 → fail
           ↓ (with failure reason + feedback)
Attempt 3 → pass

When to use: the error reason is concrete, later attempts can learn from earlier failures, and there's meaningful variation in angle or approach.

Example: root cause analysis (Phase 3)
  Attempt 1: analyze from code perspective
  Attempt 2: feedback "code analysis confidence low — try log anomaly patterns"
  Attempt 3: feedback "try tracing the call chain chronologically"

Each retry applies the previous failure as a learning signal.

Parallel Candidates

            → Candidate A → test → pass  ← select this
analysis →  → Candidate B → test → fail
            → Candidate C → test → fail

When to use: the solution space is diverse, predicting which approach will work is impossible, and exploring multiple options concurrently then selecting the best is more efficient than serial exploration.

Example: code fix (Phase 4)
  Candidate A: fix the boundary check logic
  Candidate B: fix the caller's input validation
  Candidate C: fix parseInput()'s default value handling

All three approaches could be correct. Run them concurrently,
select the one that passes tests with the highest coverage.

Selection Principle

Later attempts can learn from earlier failures → serial retry
Multiple approaches are equally plausible      → parallel candidates
Time-sensitive, can't afford serial latency    → parallel candidates
Comparing solution quality is the goal         → parallel candidates

Document the strategy in the workflow definition — it makes debugging straightforward:

phase_3_analyze:
  retry_strategy: serial          # different angles, learning from failure
  max_retries: 3
  feedback_mode: include_prev_error

phase_4_fix:
  retry_strategy: parallel        # solution space is diverse, select best
  parallel_candidates: 3
  selection_criteria: passed_tests AND max_coverage

Design Checklist

Four-layer separation

[ ] Policy (permissions/security) and Workflow (routing/structure) are in separate files
[ ] Subagent task prompts live in independent templates/ files
[ ] config.yaml centralizes mutable parameters (timeouts, retry counts)

Context passing

[ ] Every subagent invocation declares a context_mode
[ ] explicit mode lists specific fields — no whole Phase outputs passed in
[ ] Main Agent's full history is not sent to every subagent

Approval gates

[ ] Every gate has both timeout and timeout_action
[ ] Message contains enough information for a 30-second decision
[ ] Option values are enumerated types, not free text

Retry strategy

[ ] Every node with retry logic is labeled serial or parallel
[ ] Serial retries have feedback_mode (failure reason flows back to the generator)
[ ] Parallel candidates have a defined selection_criteria

Summary

The four-layer architecture's value is isolation: Policy changes don't affect routing; templates/ changes are independently testable — this is the foundation of maintainability
explicit is the safest default for Context passing: it names every field, costs fewer tokens than accumulate, is more flexible than last_only, and is easier to debug when something goes wrong
Serial retry vs parallel candidates is a directional choice: root cause analysis benefits from serial retry (learning is effective); code fix benefits from parallel candidates (solution space is diverse) — reversing them degrades both efficiency and quality

Check out PrimeSkills — a curated marketplace of AI agents and skills that have been validated in real-world, enterprise-grade workflows. No fluff, just what actually works.

Find more useful knowledge and interesting products on my Homepage

Open Source Project of the Day (#109): Trellis — Persist Project Specs, Tasks, and Memory Into Your Repository

WonderLab — Mon, 29 Jun 2026 02:52:27 +0000

Introduction

"AI coding is 10% coding and 90% re-explaining your stack. Trellis fixed the worst part of AI agents: amnesia."

This is article #109 in the Open Source Project of the Day series. Today's project is Trellis — an AI coding agent harness that persists project specs, task context, and session memory into your repository.

You spend a session with Claude Code getting things right: conventions explained, context established, good results produced. You close the terminal. Next day: start over. Re-explain the tech stack choices, re-describe the code style, re-frame the current task's background.

This has a name: agent amnesia. Every session starts fresh, and all accumulated context disappears.

Trellis stores what should be remembered inside the repository: .trellis/spec/ for conventions, .trellis/tasks/ for tasks and PRDs, .trellis/workspace/ for session journals. The agent reads these on startup — no re-explaining required.

What You'll Learn

The three-directory system: why spec / tasks / workspace each have distinct roles
The 4-phase workflow: Plan → Implement → Verify → Finish as a complete loop
Trellis Skills: what each of the four built-in workflow modules does
Comparison with CLAUDE.md / AGENTS.md: why single-file approaches become monoliths
Team scenario: how committing specs to Git benefits the whole team
Supported platforms and initialization

Prerequisites

Experience with Claude Code, Cursor, or a similar AI coding tool
Familiarity with basic Git workflow
Basic familiarity with CLAUDE.md or .cursorrules concepts

Project Background

What Is Trellis?

Trellis is an AI coding agent harness — "scaffolding for AI, guiding it along the path of your conventions."

"Harness" as a term is gaining traction in 2026 AI coding discussions: not the agent itself, but the constraints, memory, and workflow structure built around it. Trellis is among the most systematic open-source implementations in this space, cited in academic work (the "Agent Harness Engineering: A Survey" paper on OpenReview).

The core design decision: persist everything inside the Git repository. Specs can be code-reviewed. Session memory can be team-shared. Task context works across tools. This isn't just a file path choice — it's a decision to bring AI working patterns into the engineering management system.

Author / Team

Organization: Mindfold AI (mindfold-ai)
Docs: docs.trytrellis.app
License: AGPL-3.0
Stack: TypeScript 67.9% / Python 25.8%

Project Stats

⭐ GitHub Stars: 11,300+
🍴 Forks: 641+
💻 Supported platforms: 16 AI coding platforms
📄 License: AGPL-3.0

Core Features

The Three-Directory System

Trellis maintains a .trellis/ directory at the repository root with three subdirectories:

.trellis/
├── spec/           ← Project conventions (commit to Git)
│   ├── coding-standards.md
│   ├── architecture.md
│   ├── tech-stack.md
│   └── team-conventions.md
│
├── tasks/          ← Tasks and PRDs (commit to Git)
│   ├── active/
│   │   └── feature-auth/
│   │       ├── prd.md
│   │       ├── implementation-context.md
│   │       └── review-context.md
│   └── completed/
│
└── workspace/      ← Session journals (optionally .gitignored)
    └── your-name/
        └── journal.md

spec/: The core. Everything you don't want to re-explain to an agent every session: the reasoning behind technology choices, code style rules, architecture constraints, naming conventions, known pitfalls. Committed to Git, automatically injected into the agent's context at session start.

tasks/: Tasks are complete work units, not single-line descriptions. Each task has a PRD (product requirements document), implementation context (everything the agent needs to know before writing code), and review context (what to check the diff against).

workspace/: Per-developer session journals. Records what happened this session, what problems were encountered, and what the next session needs to know to continue. The agent reads this file when a new session starts.

The 4-Phase Workflow

Trellis defines a complete work loop:

Plan → Implement → Verify → Finish
  ↑                                ↓
  └──────── spec updated ←─────────┘

Phase 1: Plan (trellis-brainstorm)

Clarify requirements before writing any code:

Invoke trellis-brainstorm
    ↓
Agent walks you through requirement clarification:
  "What does success look like for this feature?"
  "Are there technical constraints to respect?"
  "What edge cases need to be handled?"
    ↓
Produces prd.md (product requirements document)
Research-heavy subtasks → dispatched to sub-agent
    ↓
PRD saved to .trellis/tasks/active/[task-name]/

Phase 2: Implement (trellis-implement)

Context auto-injected at execution time:

Invoke trellis-implement
    ↓
Automatically reads:
  - Relevant specs from .trellis/spec/
  - .trellis/tasks/active/[task-name]/prd.md
  - .trellis/workspace/[your-name]/journal.md
    ↓
Writes code according to the PRD, respecting spec constraints

Phase 3: Verify (trellis-check)

Automated review after code is written:

Invoke trellis-check
    ↓
Compare against spec: does the diff conform to standards?
Run lint, type checking, tests
Issues found → attempt self-correction
Self-correction fails → report to developer

Phase 4: Finish (trellis-update-spec)

The most valuable part of the loop:

Invoke trellis-update-spec
    ↓
Analyze new patterns, conventions, and rules discovered in this task
Promote those learnings into .trellis/spec/
    ↓
The next session starts smarter than this one

Comparison with CLAUDE.md / AGENTS.md

The problem with CLAUDE.md / .cursorrules:
  Single file → grows into a catch-all dumping ground over time
  Bulk injection → everything in context regardless of task relevance
  No task structure → no PRD, no implementation/review context separation
  No persistent memory → session ends, context is gone

What Trellis does instead:
  Modular specs → injected on demand, relevant to the task at hand
  Task context → PRD + implementation context + review context, layered
  Workspace memory → continuity across sessions
  Finish phase → spec auto-updates every time a task completes

Trellis doesn't replace CLAUDE.md — it builds structure around it. You can still have a CLAUDE.md; Trellis spec files supplement it.

Deep Dive

Installation and Initialization

# Install Trellis CLI
npm install -g @mindfoldhq/trellis@latest

# Navigate to your project
cd your-project

# Basic init (auto-detects installed AI tools)
trellis init -u your-name

# Platform-specific init
trellis init --claude-code --cursor --codex -u your-name

trellis init does the following:

Creates the .trellis/ directory structure
Generates platform-specific configuration files for detected tools
Creates initial spec templates (can be AI-generated from existing code)
Handles workspace directory .gitignore according to preference

Generating initial specs for an existing project:

In Claude Code:
"Analyze this codebase and generate initial .trellis/spec/ content
 covering the tech stack, code style, and architectural constraints"

Then review and refine the generated spec files manually

Platform Support

Trellis supports 16 AI coding platforms and generates platform-specific configuration:

Confirmed support: Claude Code, Cursor, OpenCode, Codex, GitHub Copilot, Devin, and more.

For Claude Code specifically, Trellis generates a structured CLAUDE.md and corresponding Skill files so Claude Code knows when to invoke trellis-brainstorm, trellis-implement, and the other workflow modules.

Trellis Skill System

Four built-in Skills define the workflow entry points:

Skill	When to Use	Core Behavior
`trellis-brainstorm`	Starting a new task	Guides requirement clarification, outputs PRD
`trellis-implement`	Starting to write code	Injects context, executes implementation
`trellis-check`	After code is written	Reviews against specs, self-corrects where possible
`trellis-update-spec`	After task completion	Promotes learnings back into spec

These Skills follow the agentskills.io open standard, the same format used by android/skills and other projects in the ecosystem.

Team Workflow

When spec files are committed to Git, the entire team benefits from the same standards:

Scenario: New team member joins
Traditional: Docs in Confluence (possibly stale); ask senior devs; stumble through
Trellis:
  After git clone → .trellis/spec/ has complete tech stack and conventions
  AI agent automatically follows those conventions
  New member is productive with team-standard AI workflows within a day

Scenario: Team discovers a new best practice
Traditional: Verbal knowledge transfer, or updating a doc nobody reads
Trellis:
  Someone runs trellis-update-spec → spec file updated
  Opens a PR, team reviews
  After merge, all subsequent AI sessions across the team use the new standard

Workspace Journal Format

Session journals give agents continuity between sessions:

# Journal - your-name

## 2026-06-28
### Session summary
- Completed JWT verification logic for the auth module
- Discovered a race condition in refresh token handling under concurrent requests
- Temporary fix: Redis distributed lock, but a better approach probably exists

### What the next session needs to know
- Refresh token race condition fix needs further evaluation
- Need to write integration tests for the auth module
- Edge case: same user refreshing from multiple devices simultaneously

### Open questions
- Should we implement rotating refresh tokens? Need to confirm product requirements

When the next session starts, the agent reads this journal, understands the context, and doesn't need re-briefing.

Quick Start

# Install
npm install -g @mindfoldhq/trellis@latest

# Navigate to your project
cd your-project

# Initialize (auto-detects Claude Code, Cursor, etc.)
trellis init -u your-name

# Start your first task
# In Claude Code, say:
# "Use trellis-brainstorm to start a new task: add MFA support to the auth module"

Links and Resources

🌟 GitHub: mindfold-ai/Trellis
📖 Docs: docs.trytrellis.app
🏢 Mindfold AI: github.com/mindfold-ai

Conclusion

Trellis addresses a systemic problem in the AI coding toolchain: every session starts from zero, without awareness of the project's context, the team's conventions, or the previous session's progress.

Storing specs, task context, and session memory inside the Git repository is a design decision, not an implementation detail. It means AI working patterns enter the engineering management system: specs can be reviewed, memory can be shared, changes can be tracked.

The closed-loop workflow design — especially the Finish phase promoting learnings back into specs — means the system improves with use rather than starting from the same baseline each time.

11.3k Stars signals real demand. For developers switching between multiple projects or tools, or tech leads trying to standardize AI-assisted development practices across a team, Trellis is worth serious evaluation.

Explore PrimeSkills — A marketplace for handpicked AI Agents and skills. Each is validated in real enterprise workflows, stripping away hype and keeping only what truly works.

Welcome to my Homepage for more useful insights and interesting products.

Open Source Project #108: ai-website-cloner-template — One Command, Parallel Agents, Any Website Reversed into Next.js Code

WonderLab — Sun, 28 Jun 2026 01:59:48 +0000

Introduction

"Point it at a URL, run /clone-website, and your AI agent will inspect the site, extract design tokens and assets, write component specs, and dispatch parallel builders to reconstruct every section."

This is article #108 in the "One Open Source Project a Day" series. Today's project is ai-website-cloner-template — a GitHub template repository for reverse-engineering any website into a Next.js codebase using AI coding agents.

Turning a "website screenshot" into "runnable code" is a classic Vibe Coding scenario, but most implementations stop at the surface: ask the LLM to look at a screenshot, approximate the layout, fill in placeholder content. This template takes a fundamentally different approach: it defines a rigorous multi-phase agent workflow whose core principle is "completeness beats speed" — every Builder Agent must have exact getComputedStyle() values, genuinely downloaded assets, and complete interaction state specifications before touching any code.

22k stars signals real demand for this use case. But the more interesting story is the engineering design — especially using git worktrees to achieve true parallel multi-agent construction.

What You'll Learn

The five-phase clone pipeline: reconnaissance → foundation → component specs → parallel build → assembly QA
git worktree parallel agent pattern: how each Builder Agent works in an isolated branch
Component spec file design principles: why the spec is a "contract," not a "reference"
Interaction model identification: distinguishing click-driven, scroll-driven, and time-driven behaviors before building
Cross-platform agent support: how 13 AI coding tools are all served from a single source file

Prerequisites

Experience with Claude Code, Cursor, or similar AI coding tools
Basic familiarity with Next.js
Basic understanding of git branches

Project Background

Overview

ai-website-cloner-template is a GitHub template repository (is_template: true) that pre-scaffolds a Next.js 16 + shadcn/ui + Tailwind v4 project alongside a /clone-website AI Agent Skill.

Usage pattern: use "Use this template" on GitHub to create your own repository, start your AI agent, run /clone-website <target-url>, and the agent completes the full pipeline from reconnaissance to working code.

The project's core engineering contribution isn't the tech stack choice — it's the multi-agent collaboration protocol behind the /clone-website Skill, particularly using git worktrees for genuinely parallel component builds and enforcing the "spec first, builder second" constraint.

Author / Team

Author: JCodesMore
Primary Language: TypeScript
License: MIT
Community: Discord

Project Stats

⭐ GitHub Stars: 22,100+
🍴 Forks: 3,173+ (most used to create independent projects)
📄 License: MIT
📅 Created: March 2026

Features

What It Does

Traditional "screenshot clone" approach:
Screenshot → LLM approximates layout → placeholder content → manual color/spacing corrections → iterate

ai-website-cloner-template approach:
/clone-website https://example.com
    ↓
Phase 1 Recon: screenshots + scroll/click/hover interaction sweep + design token extraction
    ↓
Phase 2 Foundation: update fonts/colors/globals.css + download all assets + extract SVG icons
    ↓
Phase 3 Specs: write spec files per section (exact CSS values + real content + interaction states)
    ↓
Phase 4 Parallel Build: git worktree per section + dispatch Builder Agents in parallel
    ↓
Phase 5 Assembly QA: merge all worktrees + wire up page + npm run build verification

Use Cases

Platform migration: Rebuild a site you own from WordPress/Webflow/Squarespace into a Next.js codebase, gaining full code ownership
Lost source code: The site is live but the repo is gone, the developer left, or the stack is too legacy to maintain — recover the code from the live version in a modern format
Learning: Deconstruct how production sites achieve specific layouts, animations, and responsive behavior by working with the actual code (not just screenshots)

Not Intended For

The README explicitly states:

Phishing or impersonation: forbidden for deceptive purposes, impersonation, or illegal activities
Passing off others' designs as your own: logos, brand assets, and original copy belong to their owners
Violating terms of service: some sites explicitly prohibit scraping or reproduction — check first

Quick Start

1. Create your own repository

On the GitHub project page, click Use this template → Create a new repository (don't clone the template repository directly).

2. Clone and install

git clone https://github.com/YOUR-USERNAME/YOUR-NEW-REPO.git
cd YOUR-NEW-REPO
npm install

3. Start Claude Code (recommended)

claude --chrome   # --chrome starts Chrome MCP for browser automation

4. Run the clone skill

/clone-website https://target-website.com

Multiple URLs can be processed in parallel:

/clone-website https://site1.com https://site2.com

5. Dev preview

npm run dev        # Start dev server
npm run check      # Run lint + typecheck + build

Supported AI Agent Platforms

Agent	Status
Claude Code	Recommended (Opus 4.7)
Codex CLI	Supported
OpenCode	Supported
GitHub Copilot	Supported
Cursor	Supported
Windsurf	Supported
Gemini CLI	Supported
Cline	Supported
Roo Code	Supported
Continue	Supported
Amazon Q	Supported
Augment Code	Supported
Aider	Supported

Cross-platform support works like this: AGENTS.md is the single source of truth for all project instructions. Running bash scripts/sync-agent-rules.sh auto-generates platform-specific copies (CLAUDE.md, GEMINI.md, .cursor/, .windsurf/, etc.) from that single file.

Deep Dive

The Five-Phase Pipeline

Phase 1: Reconnaissance

This is not just screenshots. Reconnaissance requires three mandatory tasks:

Screenshots: Full-page screenshots at 1440px (desktop) and 390px (mobile), saved to docs/design-references/. These are the visual master reference for the entire process.

Mandatory interaction sweep (the most commonly skipped step):

Scroll sweep — scroll slowly from top to bottom, observe:
  - At what scroll position does the navbar change appearance?
  - Which elements animate in when entering the viewport?
  - Which sections have scroll-snap points?
  - Is a smooth scroll library (Lenis, Locomotive Scroll) active?

Click sweep — click every element that looks interactive:
  - What content does each tab/pill switch to?
  - What modals open, what dropdowns appear?

Hover sweep — hover every element that might have hover states:
  - Color changes, scale, shadow, opacity, underlines...

Responsive sweep — test at 1440px / 768px / 390px:
  - Note layout changes and the approximate breakpoint where they occur

All findings are saved to docs/research/BEHAVIORS.md — the "behavior bible" for the entire cloning process.

Page topology: Map every distinct section from top to bottom, document each section's interaction model (static / click-driven / scroll-driven / time-driven), save as docs/research/PAGE_TOPOLOGY.md — the assembly blueprint.

Phase 2: Foundation Build

Done by the Orchestrator Agent directly — not delegated to sub-agents because it touches many files:

Update src/app/layout.tsx: configure the target site's actual fonts via next/font/google or next/font/local
Update src/app/globals.css: map the target site's color tokens (background, foreground, primary, muted...) to the shadcn variable system using oklch color space
Extract all SVG icons → save as named React components in src/components/icons.tsx
Run the asset download script (scripts/download-assets.mjs): batch-download all images and videos to public/
Verify: npm run build passes

Asset discovery runs JavaScript via browser MCP to precisely enumerate all <img>, <video>, and CSS background-image elements, including absolutely-positioned overlay layers — a section that looks like a single image is often a background watercolor + foreground UI mockup PNG + an overlay icon. Missing any layer makes the clone look empty.

// Run via browser MCP to discover all assets
JSON.stringify({
  images: [...document.querySelectorAll('img')].map(img => ({
    src: img.src || img.currentSrc,
    alt: img.alt,
    parentClasses: img.parentElement?.className,
    siblings: img.parentElement ? [...img.parentElement.querySelectorAll('img')].length : 0,
    position: getComputedStyle(img).position,
    zIndex: getComputedStyle(img).zIndex
  })),
  backgroundImages: [...document.querySelectorAll('*')].filter(el => {
    const bg = getComputedStyle(el).backgroundImage;
    return bg && bg !== 'none';
  }).map(el => ({
    url: getComputedStyle(el).backgroundImage,
    element: el.tagName + '.' + el.className?.split(' ')[0]
  })),
  // ... videos, fonts, favicons
})

Phase 3: Component Specs

Before any Builder Agent is dispatched, a spec file must be written for that section in docs/research/components/<name>.md. The spec is the contract between extraction and construction — not optional.

What the spec file contains:

A screenshot crop of the section (local path)
Exact CSS values extracted via getComputedStyle() — not eyeballed estimates
Downloaded asset local paths (the public/ path, not the original URL)
Real text content (from element.textContent, not placeholders)
All interaction states (content per tab state, CSS diff before/after scroll trigger, transition animation parameters)
Responsive breakpoint behaviors

CSS extraction script (executed via browser MCP):

(function(selector) {
  const el = document.querySelector(selector);
  const computed = getComputedStyle(el);
  const props = [
    'fontSize','fontWeight','fontFamily','lineHeight','letterSpacing',
    'color','backgroundColor','background',
    'padding','paddingTop','paddingRight','paddingBottom','paddingLeft',
    'margin','borderRadius','boxShadow','display','flexDirection',
    'gap','alignItems','justifyContent','position','zIndex',
    // ... full property list
  ];
  return Object.fromEntries(props.map(p => [p, computed[p]]));
})(selector)

Complexity budget rule: If a section's spec file exceeds ~150 lines, the section is too complex for one agent — split it into smaller pieces. This is a mechanical check that cannot be overridden with "but they're all related."

Phase 4: Parallel Build via git Worktrees

This is the key architectural decision — git worktrees give each Builder Agent an isolated working branch:

# Orchestrator creates a worktree per section
git worktree add .worktrees/hero-section feature/hero-section
git worktree add .worktrees/features-grid feature/features-grid
git worktree add .worktrees/pricing-section feature/pricing-section

# Each Builder Agent works in its own worktree
# Builder receives the full spec file content inline in its prompt
# Builder verifies: npx tsc --noEmit passes before finishing

What each Builder Agent receives:

Full spec file content (inlined into the prompt, not a path reference)
Screenshot crop path
Downloaded asset local paths
Global style system (font variables, color tokens)

The Builder doesn't need to read other sections' code or understand the overall page structure. Its only job: implement this one component to spec, with TypeScript compiling clean.

Phase 5: Assembly & QA

# Orchestrator merges all worktree branches
git merge feature/hero-section feature/features-grid feature/pricing-section ...
# Resolve merge conflicts (Orchestrator has full context for smart resolution)

# Wire up all section components in correct order in src/app/page.tsx

# Final verification
npm run build    # Must pass — no exceptions

The Single Most Expensive Mistake: Wrong Interaction Model

The SKILL file dedicates significant space to this because building a click-based UI when the original is scroll-driven means a complete rewrite, not a CSS tweak.

Identification protocol:

Don't click first. Scroll slowly and observe if anything changes on its own.
If yes → scroll-driven. Extract the mechanism: IntersectionObserver, scroll-snap, position: sticky, animation-timeline, or JS scroll listeners.
If no → then test click/hover-driven interactivity.
Document explicitly in the spec: INTERACTION MODEL: scroll-driven with IntersectionObserver or INTERACTION MODEL: click-to-switch with opacity transition.

Classic scroll-driven patterns to watch for:

A sticky sidebar where the active item auto-changes as content scrolls past (IntersectionObserver, NOT click handlers)
Tabbed/pill content that cycles when built as click-based
Smooth scroll libraries (Lenis, Locomotive Scroll) — check for .lenis class or scroll container wrappers

Project Structure

src/
  app/              # Next.js routes
  components/
    ui/             # shadcn/ui primitives
    icons.tsx       # SVG icons extracted from target (React components)
  lib/utils.ts      # cn() utility
  types/            # TypeScript interfaces
  hooks/            # Custom React hooks
public/
  images/           # Downloaded images from target
  videos/           # Downloaded videos from target
  seo/              # Favicons, OG images, webmanifest
docs/
  research/         # Extraction output: component specs, behaviors, topology
  design-references/ # Screenshots (desktop + mobile)
scripts/
  sync-agent-rules.sh  # Sync AGENTS.md to all platform formats
  sync-skills.mjs      # Sync /clone-website to all platforms
AGENTS.md           # Single source of truth for all agent instructions
CLAUDE.md           # Claude Code config (imports AGENTS.md)
GEMINI.md           # Gemini CLI config (imports AGENTS.md)

Cross-Platform Design: One Source, Many Targets

The template supports 13 AI coding platforms without maintaining 13 separate instruction sets:

What	Source of Truth	Sync Command
Project instructions	`AGENTS.md`	`bash scripts/sync-agent-rules.sh`
`/clone-website` skill	`.claude/skills/clone-website/SKILL.md`	`node scripts/sync-skills.mjs`

Each script generates platform-specific copies automatically. Agents that can read the source files natively need no regeneration.

This pattern — single source file plus generation scripts — is worth borrowing for any tool that needs to support multiple AI coding environments.

Resources

Official Links

🌟 GitHub: JCodesMore/ai-website-cloner-template
🎬 Demo video: YouTube link in the project README
💬 Discord: discord.gg/hrTSX5yTpB

Summary

ai-website-cloner-template's value isn't the tech stack choice (Next.js + shadcn + Tailwind is standard). It's the multi-agent collaboration protocol that's been thought through carefully.

A few design decisions worth internalizing:

"Completeness beats speed": Builder Agents receive everything before starting. No guessing mid-build. The constraint makes results more reliable at the cost of a slower reconnaissance phase — the author considers that tradeoff correct.

Complexity budget (150-line spec = split signal): A mechanical rule controlling task scope, not a judgment call. Engineering discipline, not intuition.

git worktree parallelism: Each Builder works in an isolated branch; the Orchestrator merges at the end. Parallelism isn't "run multiple tasks simultaneously" — it's isolated work with clear merge semantics.

Single source + sync scripts: AGENTS.md is the single source of truth for 13 platforms. One edit, one script run, all platforms updated. A pattern worth copying for any multi-environment AI toolchain.

The underlying principle — define the process rigorously enough that any capable agent can follow it, rather than relying on one specific agent to improvise correctly — is applicable well beyond website cloning.

Explore PrimeSkills — a curated marketplace of AI agents and skills, each validated against real enterprise workflows. No hype, just what actually works.

Visit my personal site for more insights and interesting products.

AI-Native Organizations Aren't About Buying Tools — They're About Making Waiting Disappear

WonderLab — Sun, 28 Jun 2026 01:54:02 +0000

I came across a piece on AI-native organizations recently, and it stuck with me. Let me work through it.

Lots of companies are doing "AI transformation." Some build internal gateways and hand out API keys to everyone. Some run company-wide training programs. Some bolt a few "smart assistants" onto their existing systems. And some — this one's my favorite — post daily token usage rankings in the company chat, as if burning more compute is the same as being more advanced.

Are any of these useful? Sure, a little. But none of them equal AI-native.

True AI-native isn't about how many models you use. It's about whether the waiting in your organization has decreased since AI showed up.

If collaboration still works the same way — people still queue up for approvals, tasks still get handed off layer by layer — then AI is just a new tool bolted onto an old organization. New hardware, running the same old operating system.

From "Tool" to "Operating System"

YC partner Diana Hu once said: AI shouldn't just be a tool that companies use — it should become the operating system that companies run on.

That's right. But it's easy to misread.

When people hear "operating system," the first instinct is: does that mean we need to build an AI platform? Connect all our systems into it?

That's exactly the problem. AI-native absolutely needs a technical foundation, but it's not fundamentally an IT project. The hard part isn't the systems — it's the unspoken habits, responsibility boundaries, and collaboration patterns baked into how an organization works.

For a CEO, "AI as operating system" really means: AI needs to enter the rules of how the organization runs. It needs to influence how tasks get assigned, how information gets used, how accountability gets defined, and how people work together.

If all you end up with is a new platform — but the rules haven't changed — that's not AI-native. It's a new system running inside an old organization.

Four Stages: Where Are You Now?

Companies don't become AI-native overnight. They tend to go through four stages.

Stage 1: Individual Efficiency

Employees start using AI to write emails, meeting notes, and summaries. This is the most common starting point, and it's easy to get there.

But it's not organizational change. Each person has just gotten faster at their own piece of the work. Collaboration hasn't changed. The people who needed to wait before still need to wait. The processes that needed to be walked through still do.

Stage 2: Node Automation

AI starts entering fixed workflows to replace repetitive work. Customer feedback comes in and AI auto-tags it, assigns priority, routes it. A support ticket arrives and AI fills in missing info, classifies the issue, and suggests a resolution. A sales call ends and AI extracts customer needs, risk signals, and next steps.

This goes further than Stage 1, but the process itself hasn't changed — you've just made one node inside the old process faster.

Stage 3: Nodes Disappear

This is the real turning point.

AI isn't just speeding up a node anymore — it's making some nodes that once felt inevitable simply unnecessary.

Before, many tasks had to wait in sequence. Now, employees can use AI to push the early-stage work to a reasonably complete state before any handoff — not necessarily the final version, but enough to keep things moving. You no longer need to wait on someone else, or another department, before the next step can start.

This is when an organization starts to genuinely get lighter. AI isn't just changing the efficiency of a node — it's changing how work flows.

Stage 4: Organizational Restructuring

Once fewer tasks require passing through multiple layers, the old processes, roles, and accountability boundaries start getting redefined.

Some roles stop being execution nodes and become standard-setters, quality gatekeepers, handlers of genuinely complex problems. Some workflows stop requiring multi-layer hand-offs and instead have one person or a small team close the loop, with key decision-makers stepping in only at judgment points.

AI-native organizations don't happen because the CEO orders processes cut. They happen because new capabilities grow in, old nodes slowly lose their reason to exist, and the organization naturally gets lighter.

Two Roles: AI Builder and Human Decider

Once an organization starts going AI-native, people's roles have to be redefined too.

The relevant distinction in future organizations won't be job titles — it'll be two kinds of roles.

AI Builder

Not necessarily an engineer. Could be product, operations, sales, finance — the job title doesn't matter. What matters is whether this person can take an ambiguous business problem and break it into a workflow AI can actually execute. Whether they can set standards, validate results, iterate, and turn something that worked once into something that can be reused.

The scarcest thing in the AI era isn't people who know how to open a tool. It's people who understand the business and can close loops in collaboration with AI.

Human Decider

This person's value isn't monitoring processes — it's making judgments. AI can generate 10 proposals, but which one aligns with company strategy? Which one carries brand risk? Which one looks effective short-term but will quietly damage the organization over time? These questions can't be delegated to a model. Models don't carry business accountability.

Which means: the more capable AI gets, the more important Human Deciders become.

One sentence summary: AI Builders push work to the point where a judgment call is possible. Human Deciders decide whether to do it, which direction to go, and how far.

Five Steps — Not "Start by Cutting Processes"

Here's a cleaner path forward.

Step 1: Build an AI transformation team — with CEO authorization

This team cannot be a side project under IT. It can't be an HR-run training initiative. AI transformation will run into old processes, old divisions of responsibility, old power structures. Without CEO-level backing, any pilot will get slowly absorbed back into the old org.

The team needs three capabilities together: know AI (understand what fits what scenario), know the business (identify real pain points, not just visible ones), know the organization (navigate the structural changes that follow).

The goal isn't to build some AI assistants. It's to find the serial bottlenecks in the business most worth breaking through, run a proof of concept, and show the company: this wasn't impossible to do faster — we've just always done it the old way.

Step 2: Build the habit of "ask AI first"

But you can't mandate this. If you require everyone to use AI a certain number of times per day, they'll manufacture conversations. If you require departments to submit AI case studies, they'll package something. Another formalism exercise.

A better approach: use incentives to surface genuine cases. A good case should answer three questions: How many people used to be involved in this? How many wait-steps did AI remove? Can this approach be reused by someone else in the same role doing the same thing?

And share these cases company-wide — not to honor the early adopters, but so others can see: this thing can be done differently.

Step 3: Turn good cases into reusable Skills

Running a case study program isn't enough on its own. If someone figures out a method and it stays on their laptop or in their head, the organization hasn't actually gotten stronger.

The transformation team's job is to pull the pattern out of each good case and turn it into a reusable Skill — something a colleague in the same role, handling the same situation, can invoke without starting from scratch.

The core of an AI-native organization isn't having a few AI experts. It's turning what the experts figured out into something the organization can replicate. Otherwise, the person who's brilliant today leaves, and everyone starts over.

Step 4: Let old processes leave the main path

Once there's a library of Skills that lets employees push work to a "ready to discuss, ready to decide" state, the nodes that once required waiting in line become optional.

Note: this isn't about slashing processes up front. Cutting things directly triggers defensiveness — from the employee's perspective, you're removing their reason to exist.

The smarter framing is: change "must always go through this node" to "involved when it's actually needed."

Concrete example: a business person writing a client proposal used to need to wait for marketing to provide materials, data team to pull analysis, and design to do layout. With the right Skills in place, they can generate the initial client insight, proposal structure, copy, and visual draft themselves. Not a final version, but enough to start a real conversation.

At that point, marketing's role shifts from "materials production node you always wait for" to "brand standards and content quality gatekeeper." The data team shifts from "report output you always wait for" to "accountable for the metric framework and genuinely complex analysis." Design shifts from "mechanical layout person" to "responsible for visual standards and high-stakes output quality."

Nodes go from "mandatory stops" to "high-value judgment points." People don't disappear — they exit low-value execution and move toward work that requires judgment, definition, and oversight.

Step 5: IT transformation comes last

Many companies get this sequence completely backwards. Start talking AI transformation, immediately kick off a systems project, spend a year building a platform, employees don't use it, business habits haven't changed — and you've just created a fancier version of the previous IT initiative.

The right order: change people's habits first, then crystallize the business method, then evaluate which methods are worth systematizing, then build the IT layer.

Early on, you genuinely don't know which use cases are real. If you build the AI platform first, you risk locking in the wrong processes at a higher level of sophistication.

CEOs: resist the urge to immediately ask "should we build an AI platform?" or "should we connect everything into a unified agent system?" Ask instead: which role has already demonstrated real efficiency gains with AI? Which Skill is getting repeatedly invoked? Which old node has already stopped being a required stop? Which scenario is genuinely worth systematizing?

When those questions have answers, IT investment won't be wasted. The IT system is not the starting point of AI-native. It's what gets built after the organization's new habits have stabilized.

Three Things CEOs Actually Need to Do

Use AI yourself.

You don't need to understand model training or infrastructure. But you need to actually use AI. Only then will you avoid being misled by subordinates, avoid getting swept up in a flashy demo and mandating it company-wide, and avoid dismissing everything because you heard AI hallucinates sometimes.

Shield and authorize the transformation team.

AI-native can't be achieved by a side project. Without CEO-level protection, every pilot gets slowly ground down by the existing org structure and turns into another "exciting initiative that faded out."

Change where resources flow.

Teams that produce real results with AI get more resources. People who can independently close problems with AI earn higher returns.

The flip side: teams that consistently reject AI, depend on inefficient handoffs, and pass problems along to processes and other departments should not keep receiving the same resources.

Organizational change doesn't happen through slogans. It happens through where resources flow.

In the End

LLM capability will spread like electricity or running water — it'll become basic infrastructure. Buying compute, buying accounts, building systems: none of that creates a moat.

What will beat you isn't a competitor of similar size with similar bloat. It'll be a team one-tenth your headcount where every person can close loops with AI, move fast, and make calls. Every business cycle they run is 10x faster than yours.

AI is, at its core, an evolutionary event. It eliminates the mechanical relay nodes, the redundant approval chains, and the managers who hide behind process to avoid accountability.

Making large companies lighter, making slow companies faster — that's what AI-native actually means.

Open Source Project #107: page-agent — A Pure-JS GUI Agent for the Browser, No Screenshots, No Plugins, No Backend

WonderLab — Sat, 27 Jun 2026 00:16:03 +0000

Introduction

"One script tag. Natural language controls your web app. No screenshots, no browser extensions, no backend, no Python."

This is article #107 in the "One Open Source Project a Day" series. Today's project is page-agent — Alibaba's open-source client-side GUI Agent library.

The dominant approach to making AI operate a browser follows one path: screenshot → multimodal LLM recognizes elements → execute action. That path has two costs: multimodal models (expensive) and a server or headless browser environment (complex infrastructure).

page-agent's answer: serializing the DOM to text is enough. Assign numeric indices to interactive elements, send the text to any LLM, get back "click element 3" as a tool call, execute it directly in the browser. The entire loop stays in-page. No screenshots. No multimodal capability needed.

What You'll Learn

Text-based DOM: how to turn a page into an LLM-readable indexed structure
ReAct loop architecture: Observe → Think (reflection + action) → Act, fully implemented in TypeScript
Reflection-Before-Action model: evaluating the previous step before planning the next
Built-in tool system: how click, input, scroll, and JS execution tools are defined
Single package vs. core package: page-agent (with UI) and @page-agent/core (pure logic)
Chrome extension + MCP Server for cross-page capability

Prerequisites

Understanding of LLM function calling (tool use) mechanics
Basic knowledge of DOM and browser events
Experience with OpenAI SDK or similar APIs

Project Background

Overview

page-agent is a pure client-side GUI Agent library that embeds LLM reasoning directly into web pages. It understands page structure through serialized DOM text and executes actions without leaving the browser.

The core architectural decision: DOM text instead of screenshots. The DOM already fully describes what elements exist on the page, what type they are, and whether they're currently interactive. Serializing this to text is more precise than a screenshot (button labels are never blurry), cheaper (no multimodal models), and faster (DOM reads are synchronous).

The project acknowledges browser-use (server-side Python browser automation) as its inspiration. page-agent's positioning is the client-side counterpart: runs inside the page, not controlling a headless browser from a server.

Author / Team

Organization: Alibaba
Primary Language: TypeScript
License: MIT
npm packages: page-agent (with UI Panel), @page-agent/core (pure agent logic)
Latest version: v1.10.0

Project Stats

📄 License: MIT
📦 npm: page-agent
💻 Stack: TypeScript + npm workspaces + Vite

Features

What It Does

Traditional browser GUI Agent (screenshot path):
Page → Screenshot → Multimodal LLM visual understanding → Return coordinates/elements → Execute
Cost: multimodal API fees + server/headless browser infrastructure

page-agent (text DOM path):
Page → Serialize DOM with indexed interactive elements → Pure text LLM reasoning
    → Return tool call: { click_element_by_index: { index: 2 } }
    → Execute directly in the page
Cost: text LLM (cheaper) + zero backend (pure frontend JS)

Use Cases

SaaS AI Copilot: Embed an AI assistant directly in your product — user says "create a new project named X" and it happens. No backend rewrite needed.
Smart form filling: Compress 20-click workflows in ERP/CRM/admin systems into a single sentence
Accessibility: Add natural language control to any web application — voice commands, screen reader enhancement
Cross-tab Agent: With the Chrome extension, agents can work across tabs (e.g., read data from a spreadsheet tab, fill it into a form in another tab)
MCP control: Through the MCP Server (Beta), external agent clients can control the browser

Quick Start

One-line integration (free Demo LLM, technical evaluation only):

<script src="https://cdn.jsdelivr.net/npm/page-agent@1.10.0/dist/iife/page-agent.demo.js" crossorigin="true"></script>

After loading, a floating Agent panel appears in the bottom-right corner. Type natural language commands directly.

NPM installation (production):

npm install page-agent

import { PageAgent } from 'page-agent'

const agent = new PageAgent({
    model: 'gpt-4o',
    baseURL: 'https://api.openai.com/v1',
    apiKey: 'YOUR_API_KEY',
    language: 'en-US',
})

const result = await agent.execute('Click the login button, then fill in the username as test@example.com')
console.log(result.success, result.message)

Using @page-agent/core (no UI panel, embedded scenarios):

import { PageAgentCore } from '@page-agent/core'
import { PageController } from '@page-agent/page-controller'

const pageController = new PageController({ enableMask: true })
const agent = new PageAgentCore({
    pageController,
    model: 'gpt-4o',
    apiKey: 'sk-...',
    maxSteps: 20,
    onAfterStep: async (agent, history) => {
        console.log('step completed', history.at(-1))
    }
})

const result = await agent.execute('Find the lowest-priced item in the product list and add it to the cart')

Supported models (any OpenAI-compatible endpoint works):

Provider	Models
OpenAI	gpt-4o, gpt-4-turbo, gpt-5.2, gpt-5.4
Anthropic	claude-opus-4.8, claude-sonnet-4, claude-haiku-3.5
Alibaba	qwen3.5-plus, qwen3.6-max, qwen3.6-flash
DeepSeek	deepseek-chat, deepseek-reasoner
Google	gemini-2.0-flash (via OpenAI-compatible endpoint)
Local	Ollama (qwen3:14b, tested on RTX 3090 24GB)

Deep Dive

Text-Based DOM: The Core Technique

page-agent's PageController converts the DOM into an indexed simplified text structure:

Raw DOM (simplified):
<div class="form-container">
  <input type="text" placeholder="Username" />
  <input type="password" placeholder="Password" />
  <button class="btn-primary">Sign In</button>
  <a href="/register">Create account</a>
</div>

Serialized for LLM (interactive elements with indices):
URL: https://example.com/login
Title: Login - My App

[0]<input placeholder="Username" />
[1]<input type="password" placeholder="Password" />
[2]<button>Sign In</button>
[3]<a>Create account</a>

Each interactive element gets a numeric index [N]. The LLM only needs to return "click [2]" or "input 'admin@example.com' into [0]."

DOM processing pipeline:

Live DOM
    ↓ dom_tree/ module
FlatDomTree (flattened tree with DomNode map)
    ↓ Dehydration (simplification)
Indexed text representation
    ↓
LLM context input
    ↓
LLM returns tool call: { click_element_by_index: { index: 2 } }
    ↓
PageController.clickElement(2) → locate HTMLElement by index → fire click

Only elements meeting all three criteria are indexed (to reduce noise):

isVisible: true — element is in or scrollable to viewport
isInteractive: true — clickable/inputtable/selectable elements
isTopElement: true — not obscured by overlapping elements

ReAct Loop Architecture

agent.execute("complete some task")
    ↓
┌─────────────────────────────────────────────┐
│         Main loop (up to maxSteps)           │
│                                             │
│  ① Observe                                  │
│     pageController.updateTree()             │
│     → refresh DOM, get current page text    │
│                                             │
│  ② Think (LLM call)                         │
│     Input: system prompt + history + DOM    │
│     LLM output (Reflection model):          │
│     {                                       │
│       evaluation_previous_goal: "...",  ←── how did the last step go?
│       memory: "...",                    ←── what to remember?
│       next_goal: "...",                 ←── what to do next?
│       action: { click_element_by_index: {index: 2} }
│     }                                       │
│                                             │
│  ③ Act                                      │
│     Execute the tool call returned by LLM   │
│     Record to history (persistent, visible  │
│     to LLM in next steps)                   │
│                                             │
│  ④ Check termination                        │
│     LLM calls done tool → return result     │
│     OR maxSteps reached                     │
└─────────────────────────────────────────────┘
    ↓
ExecutionResult { success, message, history }

Reflection-Before-Action Model

Before each LLM call, the previous step's result and full history are passed to the model, which is required to reflect before acting:

{
  "evaluation_previous_goal": "Successfully clicked the login button, page navigated to the dashboard",
  "memory": "Login complete, currently on the dashboard. Still need to find the settings page.",
  "next_goal": "Locate and click the Settings or Account option in the navigation bar",
  "action": {
    "click_element_by_index": { "index": 5 }
  }
}

evaluation_previous_goal forces the model to evaluate the previous step's outcome before proceeding — preventing blind continuation (e.g., if a click triggered nothing, the model should pivot rather than click again).

memory is the short-term memory mechanism: compressing key progress into 1-3 sentences that persist in history, so the LLM doesn't "forget" what it has already accomplished in a long multi-step task.

Built-in Tool System

Tools the LLM can call via function calling:

Tool	Purpose
`click_element_by_index`	Click element at specified index
`input_text`	Type text into input field at index
`select_dropdown_option`	Select dropdown option by text content
`scroll`	Vertical scroll (by pages or pixels)
`scroll_horizontally`	Horizontal scroll
`execute_javascript`	Execute arbitrary JS (AbortSignal supported)
`wait`	Wait 1-10 seconds (for page loads or animations)
`ask_user`	Ask the user a question (human-in-the-loop node)
`done`	Task complete, return result

Custom tools (extend or override defaults):

const agent = new PageAgent({
    model: 'gpt-4o',
    apiKey: '...',
    customTools: {
        // Add a custom tool
        get_current_user: {
            description: 'Get the currently logged-in user information',
            inputSchema: z.object({}),
            execute: async function() {
                const user = await fetchCurrentUser()
                return JSON.stringify(user)
            }
        },
        // Set to null to disable a built-in tool
        execute_javascript: null
    }
})

Monorepo Architecture

packages/
├── page-agent/        → Main package (npm: page-agent), includes UI panel
├── core/              → Pure agent logic (npm: @page-agent/core), no UI
├── llms/              → LLM client, multi-provider support
├── page-controller/   → DOM operations and visual feedback
├── ui/                → Control panel + i18n, decoupled from core
├── extension/         → Chrome extension (WXT + React)
└── website/           → Documentation site (React)

Key module boundary design:

page-controller has no knowledge of LLMs — only handles DOM operations
llms has no knowledge of page structure — only handles LLM communication
core combines them into the ReAct loop
page-agent (main package) adds a UI panel on top of core — both are independently usable

How the LLM Client Works

The llms package uses a MacroTool pattern that wraps the reflection model:

// Each LLM call expects this structure back
export interface MacroToolInput extends Partial<AgentReflection> {
    action: Record<string, any>
}

export interface AgentReflection {
    evaluation_previous_goal: string  // "Previous action succeeded/failed because..."
    memory: string                    // "Key facts to remember: ..."
    next_goal: string                 // "Next I will..."
}

The OpenAI-compatible client handles:

Converting tools to OpenAI function-calling format
Building requests with parallel_tool_calls: false (one action per step)
Provider-specific patches (DeepSeek: disable explicit tool_choice; MiniMax: temperature/tool-call compatibility)
Automatic retry with exponential backoff for 429/500 errors
Token usage tracking including prompt cache hits and reasoning tokens

Cross-Page Capability: Chrome Extension + MCP

Chrome Extension (for cross-tab workflows):

Agent runs in an extension-controlled context with access to switch tabs and read different pages' DOM
Use case: "Read data from a spreadsheet tab, paste it into a form in another tab"

MCP Server (Beta):

Exposes page-agent as MCP tools, letting external agent clients (Claude Desktop, Claude Code) control the browser remotely
Use case: connecting browser control capability into a larger agent workflow

Reliability Design

Step delay: 400ms between steps — breathing room for page renders and network requests
Click wait: 200ms after click operations — ensures DOM updates complete
Concurrency guard: Prevents concurrent execute() calls to avoid race conditions
AbortSignal support: All tool execution honors cancellation signals; execute_javascript is interruptible
Automatic retry: LLM failures (429 rate limits, 500 server errors) auto-retry with exponential backoff (100ms base)
Token tracking: Every step records promptTokens, completionTokens, prompt cache hits, and reasoning tokens

Resources

Official Links

🌟 GitHub: alibaba/page-agent
🚀 Live Demo: alibaba.github.io/page-agent
📖 Documentation: alibaba.github.io/page-agent/docs
📦 npm: page-agent

Summary

page-agent's core insight is that browser automation doesn't need to "look at" the page. The DOM is already a structured description of what exists on the page — serializing it to indexed text lets any text-only LLM understand and operate it directly. No multimodal model, no visual understanding, no coordinate targeting.

This insight dramatically lowers the barrier for GUI agents: no server required, no headless browser, no screenshots, no extra infrastructure — a single script tag or npm package running in the user's browser.

The Reflection-Before-Action model (evaluate last step → plan next step) combined with persistent memory in history is what lets multi-step tasks stay on track. The agent doesn't just chain commands blindly; it continuously re-evaluates whether its actions are having the intended effect.

For developers who want to add AI Copilot capability to a web product, or automate internal tool workflows without touching backend infrastructure, page-agent is one of the lowest-friction options currently available.

Explore PrimeSkills — a curated marketplace of AI agents and skills, each validated against real enterprise workflows. No hype, just what actually works.

Visit my personal site for more insights and interesting products.

Workflow Series (01): Foundations — Three Execution Models and Anthropic's Five Patterns

WonderLab — Fri, 26 Jun 2026 23:31:07 +0000

Workflows Are Not Flowcharts

Traditional workflows are deterministic: each node is code, branch conditions are boolean expressions, failures are predefined exception types. Same input, same output, every time.

Agent Workflows break those three assumptions:

Traditional Workflow (Airflow / n8n):
  Node             = Python function / API call (deterministic)
  Branch condition = x > 0 (boolean expression)
  Failure handling = try/except (predefined exception types)

Agent Workflow:
  Node             = LLM + tools (non-deterministic output)
  Branch condition = confidence ≥ 95% (semantic judgment)
  Failure handling = retry + human escalation + semantic fallback

Agent Workflows are one of three fundamentally different execution models, not an upgraded flowchart.

Three Execution Models

DAG (Directed Acyclic Graph)

Control flow is fully determined before execution begins. Nodes only move forward — no loops.

Examples: Airflow, n8n, GitHub Actions
Use case: data pipelines, ETL, scheduled jobs

Properties:
  → Structure is visualizable, execution order is transparent
  → No cycles (retry logic requires workarounds)
  → Right for deterministic data processing, wrong for AI tasks requiring dynamic branching

State Machine

The system has a finite set of states. Events trigger state transitions: current state + event → next state.

Examples: LangGraph, custom workflows with JSON state files
Use case: business processes with branching, retries, and human approval gates

Properties:
  → System state is serializable at any moment (supports interrupt and resume)
  → Cycles are native (retry = state rollback)
  → workflow_state.json is the state file; approval gates are waiting-for-event states

A Bug fix workflow as a state machine:

States: analyzing / fixing / reviewing / waiting_human / done / failed
Events: analyze_done / fix_passed / human_approved / timeout
Transitions:
  analyzing + analyze_done      → fixing
  fixing    + fix_passed        → reviewing
  reviewing + human_approved    → done
  reviewing + timeout           → waiting_human (escalate)

Event-Driven

Nodes communicate through messages. Each node subscribes to messages, processes them, and publishes new ones. Naturally asynchronous and long-running.

Examples: Temporal, AWS Step Functions, Apache Kafka Streams
Use case: long-running workflows (> 1 hour), enterprise-grade transactions

Properties:
  → Nodes are loosely coupled — independently deployable and scalable
  → Built-in persistence and Durable Execution guarantees
  → High operational complexity; not right for fast iteration

Which Model to Use

Data pipeline, deterministic nodes      → DAG
Branching / retries / approval gates    → State Machine
Runtime > 1 hour, strong consistency    → Event-Driven

Most AI Agent Workflows use the state machine model: it supports retry loops, serializable state, and interrupt-and-resume — all essential properties for AI workflows.

Anthropic's Five Core Patterns

Any Agent Workflow can be described using these five patterns. This vocabulary lets you communicate system architecture clearly with any engineer or stakeholder.

Pattern 1: Prompt Chaining

A → B → C
each step's output is the next step's input

When to use: Tasks decompose into ordered steps where each step's quality directly affects what follows.

Example: Bug fix workflow main chain
  Phase 1 (gather info) → Phase 2 (log analysis) → Phase 3 (root cause)
  → Phase 4 (code fix) → Phase 5 (submit) → Phase 7 (notify)

Key constraint: One step fails, the whole chain stops. Every step needs a defined on_failure behavior.

Pattern 2: Routing

Input → Classifier → [type A] → Agent A
                  → [type B] → Agent B
                  → [default] → Agent C

When to use: Different input types need different processing paths.

## Routing design example (Workflow Markdown format)

After Phase 3, route based on root cause confidence:

- confidence ≥ 95%         → proceed to Phase 4 (code fix)
- 60% ≤ confidence < 95%  → trigger Gate A (human confirms root cause)
- confidence < 60%         → retry Phase 3 (different angle, max 3 times)
- still < 60% after 3 tries → escalate to human

Key design requirement: The router must output an enumerated type, not free text. confidence < 60% is computable. "Analysis wasn't deep enough" is not.

Pattern 3: Parallelization

         → B1 →
A → split → B2 → merge → C
         → B3 →

When to use: Subtasks are independent and can run concurrently, or you need multiple perspectives to compare and select the best result.

# Fan-out: run 3 fix candidates concurrently
from concurrent.futures import ThreadPoolExecutor, as_completed

candidates = ["candidate_a", "candidate_b", "candidate_c"]

with ThreadPoolExecutor(max_workers=3) as executor:
    futures = {
        executor.submit(run_fix_candidate, c, bug_info): c
        for c in candidates
    }
    results = {}
    for future in as_completed(futures):
        candidate = futures[future]
        results[candidate] = future.result()

# Fan-in: select the best passing candidate
best = max(
    (r for r in results.values() if r["passed"]),
    key=lambda r: r["test_coverage"],
    default=None,
)

Important caveat: Parallelization speedup is capped by Amdahl's Law. Three concurrent branches plus one sequential merge step typically yields ~1.5x speedup, not 3x. (See Skill Series Article 05 for measured data.)

Pattern 4: Orchestrator-Subagents

Orchestrator (main Agent)
  ├── spawn Subagent A (isolated session)
  ├── spawn Subagent B (isolated session)
  └── collect results → make decision

When to use: Tasks decompose into independent subtasks, each needing focused context without access to the main Agent's full history.

Three design principles for subagents:

Principle 1: Input completeness
  The task prompt contains everything the subagent needs.
  It cannot depend on "implicit context from the main Agent."

Principle 2: Output contract strictness
  Output must conform to the declared JSON schema.
  {"passed": bool, "result": {...}, "error": str | null}

Principle 3: Structured failure output
  Even on failure, write {"passed": false, "error": "specific reason"}.
  A missing output file looks like a timeout to the main Agent.

Pattern 5: Evaluator-Optimizer

Generator → Evaluator → [score ≥ threshold] → output
                ↓
         [score < threshold] → feedback → Generator (retry)
                                          max_retries = 3

When to use: Output quality matters and the first attempt may not meet the bar. Iterative improvement is viable.

# Evaluation loop definition in workflow YAML
phase_4_fix:
  generator: write-android-code
  evaluator: run-unit-tests
  quality_threshold:
    min_test_coverage: 80%
    all_tests_passed: true
  on_fail:
    max_retries: 3
    feedback_to_generator: true   # pass failure reason back to generator
  on_max_retries_exceeded:
    action: human_escalation      # escalate after 3 tries, never infinite loop

Anti-pattern: An evaluation loop without max_retries runs forever. Evaluator feedback must name a specific problem. "Make it better" is not feedback.

Patterns Compose Into Real Workflows

Real production workflows combine multiple patterns. A Bug fix workflow contains all five:

Overall structure:    Prompt Chaining (main chain, Phase 1→7)

Phase 3 internally:   Evaluator-Optimizer (root cause analysis, max 3 retries)

Phase 3→4 transition: Routing (route by confidence score)

Phase 4 internally:   Parallelization (3 candidates concurrently)
                      + Evaluator-Optimizer (test each candidate)

Phase 5/7 writes:     Routing (human approval gate = special routing branch)

Overall control:      Orchestrator-Subagents (main Agent runs the state machine,
                      spawns a subagent for each Phase)

Mapping each part of your system to a pattern is the starting point for design review.

Workflow Expression Formats

A workflow's "code" can take many forms. There's no single right answer:

Format	Example	Best for
Markdown + YAML	`workflow.md` + `config.yaml`	Frequent iteration; readable by non-engineers
Python code (LangGraph)	`StateGraph` + node functions	Complex state machines; code-level testing
Visual configuration (n8n)	Canvas + JSON	API integration-heavy; AI is just one step
Natural language	`AGENTS.md` + task prompts	Early exploration; rapid prototyping

The choice affects maintainability, testability, and execution engine selection. The next article (W2: Design Patterns) covers how to structure these files.

Summary

Agent Workflows are state machines: non-deterministic nodes, semantic branching, semantic fallback — the three assumptions of traditional DAGs all fail
Five patterns are a shared vocabulary: Prompt Chaining, Routing, Parallelization, Orchestrator-Subagents, Evaluator-Optimizer — any workflow can be described with these five
Real workflows combine patterns: identifying which part of your system maps to which pattern is what system design ability looks like in practice

References

Check out PrimeSkills — a curated marketplace of AI agents and skills that have been validated in real-world, enterprise-grade workflows. No fluff, just what actually works.

Find more useful knowledge and interesting products on my Homepage

Open Source Project of the Day (#106): android/skills — Google's Official AI Skill Library for Android Development

WonderLab — Fri, 26 Jun 2026 03:26:06 +0000

Introduction

"Android Skills cover the workflows where LLMs underperform — not the areas they've already mastered."

This is article #106 in the Open Source Project of the Day series. Today's project is android/skills — Google Android team's official AI skill library.

LLMs are already competent at a lot of Android code. Standard RecyclerViews, basic Jetpack Compose layouts, simple network calls — these appear extensively in training data and models handle them reasonably well.

The hard parts are different: the areas of the Android framework that keep evolving — migrating from Camera1 to CameraX, configuring builds with AGP 9's new approach, understanding the architectural differences between Navigation 3 and the old Navigation Component, correctly configuring ProGuard/R8 rules. Official best practices shift constantly in these areas, and LLM training data doesn't keep up.

android/skills packages developer.android.com's current best practices as Skill files specifically to fill those knowledge gaps. Google's internal data from the launch blog: tasks completed 3× faster compared to agents working without skills, and token consumption reduced by more than 70%.

What You'll Learn

What all 13 official skills cover — which Android scenarios Google identifies as LLM weak spots
Installation and usage: Android CLI commands + Android Studio integration
On-demand loading architecture: how skills activate automatically without polluting the context window
Writing custom skills: encoding your team's workflows into private SKILL.md files
Compatibility with Claude Code, Gemini CLI, Codex, and others
The companion tools: Android CLI and Android Knowledge Base

Prerequisites

Android development experience (familiarity with Gradle build system, Jetpack libraries)
Experience with Claude Code, Gemini CLI, or a similar AI coding tool
Basic familiarity with the agent skills concept

Project Background

What Is android/skills?

android/skills is Google's official Android development AI skill repository, released alongside Android CLI in April 2026.

Skill files are Markdown format (SKILL.md) following the agentskills.io open standard. Each skill contains: metadata (name, description, trigger conditions) + step-by-step execution instructions + optional scripts and reference documentation.

The selection criterion is explicit: focus on scenarios where LLM evaluations show underperformance, not areas where models already do well (like basic Compose components). That explains why the skill list doesn't include "write a Button" but does include "migrate from Camera1 to CameraX."

Author / Team

Team: Google Android Developer Relations
License: Apache-2.0
Version: v1.0.2 (June 2026)
Docs: developer.android.com/tools/agents/android-skills

Project Stats

⭐ GitHub Stars: 5,900+
🍴 Forks: 328+
📦 Releases: 14
📄 License: Apache-2.0

All 13 Official Skills

Category	Skill	Problem It Addresses
Build	AGP 9 Upgrade	Breaking changes and migration path for AGP 9
Camera	Camera1 → CameraX	Camera API migration best practices
Device AI	App Functions	On-device AI feature integration
Dev Tools	Android CLI	Using Android CLI itself
Identity	Verified Email	Email verification implementation
UI	Jetpack Compose	Best practices for Compose weak spots
Navigation	Navigation 3	Nav3 setup and migration from old Nav
Performance	R8 Analyzer	R8 configuration audit and optimization
Security	Android Intent Security	Intent security best practices
System	Edge-to-Edge	Modern edge-to-edge UI implementation
Testing	Testing Setup	Test infrastructure configuration
Wear	Wear Compose M3	M3 components for Wear OS
XR	Display Glasses (Compose Glimmer)	Compose for XR devices

A few worth highlighting:

R8 Analyzer: ProGuard/R8 rules are among the most difficult parts of an Android build to tune. LLMs typically give generic R8 rule suggestions without precision for specific scenarios (reflection, third-party library obfuscation). This skill encodes the complete R8 configuration analysis workflow.

AGP 9 Upgrade: Every major AGP version introduces breaking changes. AGP 9 includes deprecated APIs and new build behavior that exists in almost no training data. The skill provides the current up-to-date upgrade path.

Camera1 → CameraX: Camera1 API has been deprecated for years, but many older projects still use it. The migration path has details — like the Camera2 to CameraX adapter layer — that LLMs handle poorly.

Navigation 3: Navigation 3 and the old Navigation Component differ architecturally, not just at the API level. The skill includes design decisions and migration guidance.

Core Features

Installation

Method 1: Android CLI (recommended)

# List all available skills
android skills list

# Install a single skill
android skills add --skill=r8-analyzer --project=.

# Install all skills (across all detected agents)
android skills add --all

# Target specific agents
android skills add --skill=navigation-3 --agent=claude-code,gemini-cli

If no existing agent configuration is detected, skills install to ~/.gemini/antigravity/skills by default.

Install locations by agent:

Claude Code: ~/.claude/skills/
Gemini CLI: ~/.gemini/skills/
Android Studio: .skills/ or .agent/skills/ at project root

Method 2: Android Studio

Download the skill directory from GitHub
Import via Android Studio → Gemini → Skills
Or place the skill directory directly under .skills/ in project root

Usage

Automatic activation:

Once installed, when an AI agent detects that a prompt matches a skill's description, the skill loads automatically.

You say to Claude Code: "Update this Activity to support edge-to-edge UI"
        ↓
Agent detects "edge-to-edge" context, matches skill description
        ↓
Edge-to-Edge skill loaded (SKILL.md + associated resources)
        ↓
Task executed using the skill's step-by-step guidance

Manual invocation (Android Studio):

Type @skill-name in the Gemini chat to trigger directly:

@edge-to-edge Help me update the WindowInsets handling in this Activity

On-Demand Loading Architecture

Skills aren't all loaded into the context window upfront — they're pulled on demand:

Request arrives
    ↓
Agent reads all skill metadata (description fields — lightweight)
    ↓
Relevant skill identified via description matching
    ↓
Full SKILL.md + attached resources loaded into context window
    ↓
Task executes with complete expert context

No matching skill: nothing loaded, context window unaffected

This avoids the inefficient pattern of "stuff all skills into the system prompt" — only relevant knowledge loads, only when it's needed.

Deep Dive

SKILL.md Format

Both official and custom skills use the same format:

---
name: r8-analyzer              # max 64 chars, lowercase and hyphens only
description: >                 # max 1024 chars — this is what agents use to match
  Use this skill when the user needs to analyze or optimize an Android
  app's R8/ProGuard configuration. Applicable when debugging obfuscation
  issues, reducing APK size, or fixing runtime crashes after enabling R8.
metadata:
  author: android
  version: "1.0"
---

## Skill Instructions

(Markdown step-by-step instructions here, target 10,000–20,000 characters)

### Step 1: Analyze existing configuration
...

To run a helper script: `scripts/analyze_rules.py`
Reference docs: See `references/r8-guide.md`

The description field is critical: these 1024 characters determine when an agent activates this skill. Too broad ("for Android development") causes false triggers; too narrow misses legitimate activation points. Writing good descriptions is where skill quality lives.

Custom Skills: Encoding Your Team's Patterns

This is the most underappreciated capability in android/skills: any team can write their own skills in the same format.

Typical use cases:

Your team has a standard module structure convention
→ Write that convention as a SKILL.md
→ Place it in the project's .skills/ directory
→ Every time AI creates a new module, it follows your convention automatically

Directory structure:

project-root/
└── .skills/
    ├── team-module-template/
    │   ├── SKILL.md            # Required, case-sensitive
    │   ├── scripts/
    │   │   └── create_module.sh
    │   └── references/
    │       └── architecture-guide.md
    ├── internal-api-patterns/
    │   └── SKILL.md
    └── ci-setup/
        └── SKILL.md

These private skills are scoped to the project directory — they don't affect other projects.

Important: If you modify an official skill, rename it first before modifying — android skills add will overwrite skills with matching names on update.

The Companion Toolchain

android/skills is part of a three-component release:

Android CLI:

android sdk install         # Download only the SDK components you need
android create              # Create projects from official templates
android emulator            # Manage virtual devices
android run                 # Build and deploy apps
android skills              # Manage skills
android docs                # Access the Knowledge Base

The CLI's purpose: let AI agents operate the Android toolchain through standardized commands, reducing failures caused by environment differences (for example, ./gradlew assembleDebug path variations across environments).

Android Knowledge Base:

Continuously syncs developer.android.com, Firebase docs, Kotlin docs
Addresses the LLM training data staleness problem
Accessed through the android docs command

Claude Code Integration

android/skills is fully compatible with Claude Code. After installing:

android skills add --all --agent=claude-code

With skill files in ~/.claude/skills/, Claude Code automatically detects and loads relevant skills when handling Android tasks — no additional configuration needed.

Links and Resources

Official Resources

🌟 GitHub: android/skills
📖 Docs: developer.android.com/tools/agents/android-skills
🛠 Android CLI: developer.android.com/tools/agents/android-cli
🏗 Android Studio integration: developer.android.com/studio/gemini/skills
🌐 Agent Skills standard: agentskills.io

Conclusion

android/skills' value isn't just "13 skill files." It's Google's public answer to two questions: which Android development scenarios are genuine LLM weak spots, and how to fill those gaps with structured skill files that agents can execute.

"Focus on areas where LLM evaluations show underperformance" is a principle worth studying. It explains why these skills have practical value — they're not redundant with what LLMs already know; they're targeted at specific knowledge gaps.

The open custom skill format means any team can apply the same mechanism to internal architecture conventions, code style guidelines, and common operational workflows — encoding them as AI-executable skills instead of repeatedly pasting them into system prompts.

For Android developers, this is one of the most direct AI toolchain upgrades currently available — Google-maintained, continuously updated, compatible with multiple agents.

Explore PrimeSkills — A marketplace for handpicked AI Agents and skills. Each is validated in real enterprise workflows, stripping away hype and keeping only what truly works.

Welcome to my Homepage for more useful insights and interesting products.