Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Requirements Specification: Holochain Agent Skill

Discovery session: 2026-03-12 Status: v1 scope confirmed

Problem Statement

The Holochain developer ecosystem lacks a comprehensive AI coding assistant skill that covers the full development cycle in one place. Existing documentation is scattered across developer.holochain.org, GitHub repos, and community channels. New developers face steep learning curves; experienced developers lack a fast co-pilot for implementation patterns. This skill addresses both by providing a structured, context-aware assistant that works across the full spiral: architecture, design, scaffolding, implementation, testing, and deployment.

A secondary goal is enabling the wider Holochain community to benefit from AI-assisted development without requiring PAI (Personal AI Infrastructure) — the skill must work as a standalone agent skill with zero external dependencies.

Target Users

PersonaContextPrimary Need
Junior Holochain developerLearning the framework, first hAppGuided workflows, explanations, scaffold commands
Experienced Holochain developerActive project, knows the patternsFast pattern lookup, CRUD generation, debugging help
Full-stack developer new to HolochainKnows Rust/TypeScript, learning DHT conceptsArchitecture explanation, data model design, TypeScript client integration

Functional Requirements

IDRequirementPriorityAcceptance Criteria
FR-01Skill must cover Architecture domainMustreferences/architecture.md loads on request; covers coordinator/integrity split, DNA structure, Nix, progenitor, multi-DNA, private entries
FR-02Skill must cover Design domainMustreferences/workflows/design-data-model.md guides entry/link type design with output artifacts
FR-03Skill must cover Scaffold domainMustreferences/scaffolding.md + references/workflows/scaffold.md cover: Holonix setup, Nix flake, hc CLI, hc scaffold commands, new project workflow, add-domain-to-existing workflow
FR-04Scaffold workflow follows official Holochain documentationMustCommands and patterns reference developer.holochain.org; version pins current (hdk=0.7.0, hdi=0.8.0)
FR-05Skill must cover Implementation domainMustreferences/patterns.md covers entry types, link types, CRUD, cross-zome calls, signals, validation, HDK 0.7 API
FR-06Skill must cover Testing domainMustreferences/testing.md covers Sweettest setup, two-agent scenarios, await_consistency, update/delete patterns
FR-07Skill must cover Deployment domainMustreferences/deployment.md + references/workflows/package-and-deploy.md cover Kangaroo-Electron packaging, CI/CD, versioning
FR-08Skill must be PAI-independentMustNo voice notification curl, no SKILLCUSTOMIZATIONS hook, no PROJECTS.md references, no Algorithm routing; works in vanilla Claude Code
FR-09Skill must include installation documentationMustREADME.md with 3 installation options (global, project-local, symlink), quick start examples
FR-10Domain correspondence with PAI versionShouldSame sections, same knowledge depth, same workflow structure — different wrappers
FR-11Skill routing covers all 5 workflowsMustSKILL.md routing table maps natural language triggers to correct workflows
FR-12Context files load on demandMustSKILL.md specifies which context file to load for each topic; not all pre-loaded

Non-Functional Requirements

IDCategoryRequirementTarget
NFR-01PortabilityWorks with zero PAI infrastructureVerified by install in fresh Claude Code with no ~/.claude/PAI/
NFR-02CurrencyVersion pins match current stable Holochainhdk=0.7.0, hdi=0.8.0, holonix ref=main-0.7 at release
NFR-03CompletenessAll 6 domains have contentNo stub files in v1 release
NFR-04AccuracyCode examples compile and run correctlyExamples tested against real hAppenings/Nondominium codebase

Constraints

  • v1 conforms to Agent Skills Open Standard — compatible with Claude Code, GitHub Copilot, Cursor, Augment, and Codex
  • Ecosystem expansion deferred to v2: hREA, unyt, ADAM, and deep holochain-open-dev component patterns are not in scope. Wind Tunnel ships in v1.0 (references/wind-tunnel.md), and SKILL.md carries a companion-library currency table so users are not steered at 0.6-era tooling
  • Two independent codebases for v1 — PAI version and vanilla version developed separately; integration/merge post-v1
  • No GUI in v1 — visual tooling, diagram generation, and no-code interfaces are v3+ vision
  • Official docs anchor — Scaffold workflow must follow developer.holochain.org, not invent conventions

Decisions

Settled for v1.0 on 2026-08-17.

QuestionDecisionEvidence
Public repo locationPersonal GitHub, Soushi888/holochain-agent-skills, Apache-2.0. Moving to a community org stays possible later and costs nothing nowThe repo is already there; LICENSE is Apache-2.0
Contribution modelOpen from day oneCONTRIBUTING.md, CODE_OF_CONDUCT.md (Contributor Covenant 2.1), issue forms including a dedicated stale-version report, and a PR template all ship in v1.0

Still open, needs a maintainer call

  • Community discovery: how to publicize to the Holochain developer community. Candidates are the Holochain Discord, the developer forum, and the holochain-open-dev orbit. Not a code decision, so it does not gate v1.0.
  • PAI merge trigger: time-based or milestone-based. Out of scope for the public repo, which must stay PAI-independent by constraint.

Deferred (v2+)

FeatureTarget VersionDescription
hREA / ValueFlows sub-skillv2Scaffold and implement ValueFlows-compatible zomes
holochain-open-dev patternsv2Profiles, links to other happs, linked devices
ADAM (coasys) integrationv2AD4M perspectives and expression languages
unyt integrationv2Unit-aware numeric types for resource tracking
Holo hosting / edge nodesv2HTTP gateway, HolOS, Holo Node ISO setup
Cross-LLM portabilityv2Adapt for GLM 5, other AI clients with skill support
Skill graph / ecosystem orchestratorv2Parent skill routing to domain sub-skills
GUI / visual programmingv3+No-code interface with DHT model explorer
Diagram generationv3+Visual architecture and data flow diagrams
Progressive disclosure UIv3+Junior/senior mode switching