despiegk commented

Owner

Story: AI-First Holochain App Development Kit

Goal

Create a Holochain AI Instruction Layer so that:

Given this repo + a short prompt, an AI agent can reliably generate a working Holochain app (DNA, zomes, tests, client).

This story exists to remove Holochain friction for AI and make development as productive as NEAR.

Core Idea

We do not ask the AI to “figure out Holochain”.

Instead, we:

Curate minimal Holochain knowledge
Encode best practices
Provide strong defaults
Give the AI explicit rules + patterns

The repo becomes an AI scaffold, not just a codebase.

Requirements

1. AI Instruction File (Mandatory)

File: AI_INSTRUCTIONS.md

This file is written for an AI, not for humans.

It must include:

Mental model of Holochain in <1 page
Clear mapping:
- What is data
- What is validation
- What is authority
Explicit do / don’t rules
Canonical patterns (copy-pasteable)

The AI must never guess structure.

2. Curated Holochain Knowledge (Local)

Directory: docs/holochain/

Requirements:

Extract only what is needed to build apps:
- Zomes
- Entries
- Validation callbacks
- Extern functions
- Conductor config
No links to random blog posts
No deep theory
Prefer short excerpts over full docs

Goal: zero web browsing required by the AI.

3. Golden App Template (Reference)

Directory: examples/golden_app/

Must include:

One DNA
One integrity zome
One coordinator zome
Full CRUD flow
Validation rules
Rust client

This is the ground truth the AI imitates.

4. Prompt-Driven App Generation

We define canonical prompts that must work.

Example prompt:

“Create a fixed-rate liquidity pool where admins set exchange rates and users can deposit, swap, and withdraw assets.”

Requirements

AI must know:
- Where to put logic
- Where to put validation
- How to structure data
No manual restructuring afterward

5. Explicit Best Practices (Hard Rules)

The AI instructions must enforce:

Integrity zomes contain only validation + data types
Coordinator zomes contain only business logic
No global mutable state
All invariants enforced in validation
All externs documented in one place

Violations = failure.

6. AI-Friendly Error Strategy

Requirements:

Validation errors must be:
- Deterministic
- Human-readable
- Stable strings (no random formatting)

This is critical for AI iteration.

7. Automation & Scripts

The repo must expose one obvious path:

./install.sh
./build.sh
./run.sh
cargo run -p client

AI must be able to reason about:

Where the node runs
How DNA is rebuilt
How state resets

Success Criteria

This story is done when:

An AI agent can:
- Generate a new Holochain app
- From a short spec
- Without reading external docs
The generated app:
- Compiles
- Runs
- Enforces invariants correctly

Explicit Comparison Goal (Hidden but Intentional)

This setup allows a fair comparison:

Is Holochain still “hard”, or was it just undocumented for AI?

# Story: AI-First Holochain App Development Kit ## Goal Create a **Holochain AI Instruction Layer** so that: > Given this repo + a short prompt, an AI agent can reliably generate a **working Holochain app** (DNA, zomes, tests, client). This story exists to **remove Holochain friction for AI** and make development **as productive as NEAR**. --- ## Core Idea We do **not** ask the AI to “figure out Holochain”. Instead, we: * Curate **minimal Holochain knowledge** * Encode **best practices** * Provide **strong defaults** * Give the AI **explicit rules + patterns** The repo becomes an **AI scaffold**, not just a codebase. --- ## Requirements ### 1. AI Instruction File (Mandatory) **File:** `AI_INSTRUCTIONS.md` This file is written **for an AI, not for humans**. It must include: * Mental model of Holochain in <1 page * Clear mapping: * *What is data* * *What is validation* * *What is authority* * Explicit do / don’t rules * Canonical patterns (copy-pasteable) The AI must never guess structure. --- ### 2. Curated Holochain Knowledge (Local) **Directory:** `docs/holochain/` Requirements: * Extract **only** what is needed to build apps: * Zomes * Entries * Validation callbacks * Extern functions * Conductor config * No links to random blog posts * No deep theory * Prefer short excerpts over full docs Goal: **zero web browsing required by the AI**. --- ### 3. Golden App Template (Reference) **Directory:** `examples/golden_app/` Must include: * One DNA * One integrity zome * One coordinator zome * Full CRUD flow * Validation rules * Rust client This is the **ground truth** the AI imitates. --- ### 4. Prompt-Driven App Generation We define **canonical prompts** that must work. Example prompt: > “Create a fixed-rate liquidity pool where admins set exchange rates and users can deposit, swap, and withdraw assets.” **Requirements** * AI must know: * Where to put logic * Where to put validation * How to structure data * No manual restructuring afterward --- ### 5. Explicit Best Practices (Hard Rules) The AI instructions must enforce: * Integrity zomes contain **only validation + data types** * Coordinator zomes contain **only business logic** * No global mutable state * All invariants enforced in validation * All externs documented in one place Violations = failure. --- ### 6. AI-Friendly Error Strategy Requirements: * Validation errors must be: * Deterministic * Human-readable * Stable strings (no random formatting) This is critical for AI iteration. --- ### 7. Automation & Scripts The repo must expose **one obvious path**: ```bash ./install.sh ./build.sh ./run.sh cargo run -p client ``` AI must be able to reason about: * Where the node runs * How DNA is rebuilt * How state resets --- ## Success Criteria This story is done when: * An AI agent can: * Generate a **new Holochain app** * From a **short spec** * Without reading external docs * The generated app: * Compiles * Runs * Enforces invariants correctly --- ## Explicit Comparison Goal (Hidden but Intentional) This setup allows a **fair comparison**: > *Is Holochain still “hard”, or was it just undocumented for AI?*

lee was assigned by despiegk

2026-01-06 08:22:44 +00:00

lee commented

2026-01-09 16:16:49 +00:00

Member

Still working on the plan, however as demonstrated by #4, Claude Opus does not have a lot of friction to implement a (basic) holochain app when running in planning mode then moving to coding. There it was only mentioned to use the system holochain binaries (so don't use nix), which could potentially be a source of friction. Afterwards development appeared to be smooth, with some minor hold ups when it needed to verify and correct library call signatures

Rows
Columns

Story: AI-First Holochain App Development Kit #5