holochain

Holochain Development Skill

Expert assistant for Holochain hApp development. Covers the full development spiral: architecture, design, scaffolding, implementation, testing, and deployment.

Proactive Invocation Rule

Always invoke this skill in the PLAN phase when the task touches a Holochain project. Do not wait to be asked explicitly.

Trigger conditions — any of these means the skill should be loaded before coding begins:

• Working directory is a Holochain project (contains workdir/.happ or dnas//zomes/)
• Task involves .rs files inside zomes/coordinator/ or zomes/integrity/
• Task involves entry types, link types, cross-DNA calls, or zome functions
• Task involves a PR on a Holochain project

When proactively invoked: load Architecture.md + Patterns.md, run the ReviewZome checklist against any files being modified, surface issues before implementation begins.

Workflow Routing

| Workflow | Trigger | File | |----------|---------|------| | ReviewZome | review zome, audit zome, check implementation, validate patterns, before implementing, PR review, code review on zome | Workflows/ReviewZome.md | | DesignDataModel | design data model, model entries, what entries, what links, DHT schema | Workflows/DesignDataModel.md | | Scaffold | scaffold, new happ, new project, setup environment, init project, Holonix, nix develop, hc scaffold | Workflows/Scaffold.md | | ManualScaffold | create project files, scaffold without CLI, manual scaffold, AI creates files, no hc scaffold, scaffold in session | Workflows/ManualScaffold.md | | ImplementZome | implement zome, create zome, scaffold zome, write zome | Workflows/ImplementZome.md | | DesignAccessControl | design access control, who can call, cap grant design | Workflows/DesignAccessControl.md | | PackageAndDeploy | deploy, package, distribute, kangaroo, installer, desktop app, webhapp | Workflows/PackageAndDeploy.md |

Context Files

Load on demand based on task:

| File | Load When | |------|-----------| | Architecture.md | Coordinator/integrity split, DNA structure, Cargo workspace, Nix, dna_info, network_seed, private entries, multi-DNA (multiple roles, bridge call, OtherRole) | | Progenitor.md | Progenitor pattern, DnaProperties struct, check_if_progenitor, bootstrap mode, coordinator guard, integrity enforcement (Moss pattern), auto-registration in create_user, deploy-time injection (dna.yaml / Sweettest / Kangaroo / Moss) | | Scaffold.md | New project setup, Holonix installation, Nix flake, hc CLI, hc scaffold commands, adding a new domain to existing project | | Patterns.md | Entry types, link types, CRUD, cross-zome calls, validation, HDK 0.6 API (GetStrategy, LinkQuery, Local vs Network), must_get, signals (remote signal, init cap grant) | | AccessControl.md | Cap grants, capability system, cap claim, recv_remote_signal setup, admin-only access | | CellCloning.md | Cell cloning, partitioned data, clone roles, createCloneCell, clone_limit | | ErrorHandling.md | Error types, WasmError, ExternResult patterns, thiserror | | Testing.md | Four-layer strategy, Sweettest (Rust-native), E2E Playwright + AdminWebsocket, Wind-Tunnel performance | | WindTunnel.md | Performance/load testing with wind-tunnel: ScenarioDefinitionBuilder, call_zome, ReportMetric, multi-agent roles, DHT sync lag measurement, InfluxDB metrics pipeline | | TypeScript.md | holochain-client setup, callZome, signals, SvelteKit integration | | Deployment.md | Packaging, distributing, Kangaroo-Electron, installers, desktop app, versioning |

Quick Reference

Versions (current stable):  hdk = "=0.6.1"   hdi = "=0.7.1"   holonix ref=main-0.6
Dev commands:  nix develop  |  hc s sandbox generate workdir/  |  bun run test
Scaffold:      hc scaffold entry-type MyEntry  |  hc scaffold link-type AgentToMyEntry

Common Pitfalls Checklist

Run this against any zome code being written or reviewed. Each item is a class of bug that has burned projects before.

Entry Schema Evolution

• [ ] #[serde(default)] on new optional fields — Any field added to an existing entry struct after initial deployment MUST have #[serde(default)]. Without it, existing entries serialized before the field existed will fail to deserialize. Option<T> alone is NOT sufficient.

``rust #[serde(default)] // ← REQUIRED for fields added post-deployment pub new_field: Option<ActionHash>, ``

Cross-DNA Calls

• [ ] ZomeCallResponse is exhaustive — HDK 0.6 has 5 variants: Ok, Unauthorized, AuthenticationFailed, NetworkError, CountersigningSession. Wildcard _ is safe but hides new variants. Exhaustive match is preferred.
• [ ] Role name matches happ.yaml — CallTargetCell::OtherRole("role_name") must exactly match the role name in workdir/happ.yaml. Typos fail silently at runtime.
• [ ] Zome name matches coordinator crate name — ZomeName("zome_name") must match the coordinator's name in Cargo.toml. Check both.
• [ ] Local mirror structs for cross-DNA types — Avoid importing the remote DNA's Cargo crate. Define a local serialization mirror struct instead.

Validation Rules

• [ ] No DHT reads in validate() — validate() must be deterministic. No get(), get_links(), agent_info(), sys_time(). Only inspect the op itself.
• [ ] Use op.flattened::<EntryTypes, LinkTypes>() — Not the old op.to_type(). Patterns.md has the correct pattern.

HDK 0.6 API

• [ ] delete_link() requires GetOptions — delete_link(hash, GetOptions::default()) not delete_link(hash).
• [ ] get_links() uses LinkQuery::try_new() — Not GetLinksInputBuilder for most cases.
• [ ] GetStrategy::Local vs Network — Use Local for own-data queries (fast, no network), Network for DHT queries (cross-agent data).

Shared Utility Patterns (project-specific)

• [ ] agent_pub_key and created_at are NOT entry fields — They live in the action header. Remove them from entry structs.
• [ ] If using a shared utility crate — verify intra-DNA and cross-DNA call helpers are used consistently rather than raw call() inline.

Examples

Example 1: Design a new entry type for a marketplace listing

User: "I need to model a Listing entry with status transitions"
→ Loads Patterns.md (entry types, status enum, link types)
→ Designs ListingStatus enum (Active/Archived/Deleted)
→ Defines link types (AgentToListing, PathToListing, ListingUpdates)
→ Implements soft-delete via status field update, not entry deletion

Example 2: Debug a cross-agent test that fails intermittently

User: "My Sweettest passes alone but fails when another agent reads the entry"
→ Loads Testing.md
→ Identifies missing await_consistency call before cross-agent read
→ Adds await_consistency_60s([&alice, &bob]).await after Alice's create, before Bob's get
→ Test passes reliably

Example 3: Scaffold a new hApp from scratch

User: "Start a new Holochain project for a community coordination app"
→ Loads Scaffold.md + Workflows/Scaffold.md
→ If hc scaffold CLI is available: guides nix flake setup → hc scaffold happ → entry types
→ If no CLI (AI coding session): invokes Workflows/ManualScaffold.md → writes identical structure
→ Both paths produce the same standard hc scaffold architecture
→ Verifies compilation with hc s sandbox generate workdir/

Example 4: Implement CRUD for a new zome

User: "Implement a full resource zome with create, read, update, delete"
→ Loads Architecture.md + Patterns.md
→ Invokes Workflows/ImplementZome.md
→ Creates integrity crate (entry struct, link enum, validation)
→ Creates coordinator crate (create/read/update/delete functions)
→ Writes Sweettest tests at foundation + integration layers