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

Context Files

Load on demand based on task:

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