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.

  #[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