Tentacle Package Specification

Version: 4.0.0
Status: Foundational Draft
Category: Package Format / Interoperability

JellyFishNinja Plugin Package Format

See: Foundational Intent — Ethical Use Statement

Abstract

This document defines the Tentacle package format for JellyFishNinja, a developer environment automation system. A Tentacle is a self-contained package that bundles shell functions, AI components, and installation automation into a single distributable unit. This specification establishes the structure, manifest format, versioning, and lifecycle requirements for Tentacle packages.

Introduction
Terminology
Package Structure
Manifest Specification
Fish Layer
Jelly Layer
Install Layer
Dependency Resolution
Versioning
Distribution
Security
Lockfile Format
Lifecycle Hooks
Platform Support
Examples
Plugin Generation

1. Introduction

1.1 Purpose

The Tentacle package format provides a standardized method for packaging, distributing, and installing developer tools, shell functions, and AI components within the JellyFishNinja ecosystem. This specification ensures interoperability between package authors, registries, and the JellyFishNinja runtime.

1.2 Scope

This specification covers the structure and contents of Tentacle packages, the manifest format, dependency resolution, installation procedures, and security requirements. It does not cover the JellyFishNinja runtime implementation, registry protocols, or the Ninja build system integration details.

1.3 Conformance

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

1.4 Document Conventions

Code examples use YAML for configuration files and Fish shell syntax for shell scripts. File paths use forward slashes and are relative to the package root unless otherwise specified.

2. Terminology

Tentacle: A package conforming to this specification, identified by the .tentacle directory suffix.

Fish: The Fish shell interface layer containing shell functions and trigger bindings.

Jelly: The AI logic layer containing skills, commands, and agents for Claude integration. This is the source format that gets transformed into provider-specific formats.

Stinger: A future extension point for AI defense and enhancement agents (reserved, not yet specified).

Trigger: A single-character key binding that invokes a Fish function when pressed on an empty command line.

Handler: A Fish function invoked by a trigger.

Manifest: The tentacle.yaml file describing package metadata, dependencies, and contents.

Registry: A service hosting Tentacle packages for discovery and download.

Lockfile: A generated file (tentacle.lock) recording the exact installed state of packages.

Build Target: An AI provider (e.g., claude, gemini) for which plugin output is generated.

3. Package Structure

3.1 Directory Layout

A Tentacle package MUST be a directory with the .tentacle suffix containing at minimum a tentacle.yaml manifest file. The canonical structure is:

<name>.tentacle/
├── tentacle.yaml           # REQUIRED: Package manifest
├── README.md               # RECOMMENDED: Package documentation
├── LICENSE                 # RECOMMENDED: License file
├── CHANGELOG.md            # OPTIONAL: Version history
├── fish/                   # REQUIRED: Fish shell layer
│   ├── init.fish           # OPTIONAL: Initialization script
│   └── __tentacle_<name>_*.fish # Function files
├── jelly/                  # OPTIONAL: AI logic layer (SOURCE)
│   ├── skills/             # Skill definitions (directory format only)
│   │   └── skill-name/     # Each skill is a directory
│   │       ├── SKILL.md    # Main skill definition (REQUIRED)
│   │       ├── prompts/    # 3-step workflow prompts (OPTIONAL)
│   │       └── references/ # Skill-specific references (OPTIONAL)
│   ├── commands/           # Command definitions
│   ├── agents/             # Agent definitions
│   ├── references/         # Shared reference documentation
│   └── .mcp.json           # MCP server config (optional)
├── jelly.md                # OPTIONAL: Single-file AI components (alternative)
├── gnosis/                 # OPTIONAL: Mental models for self-improving skills
│   └── *.json              # Per-skill gnosis files (evolving knowledge)
├── claude/                 # GENERATED: Claude Code plugin format (BUILD OUTPUT)
│   ├── .claude-plugin/
│   │   └── plugin.json
│   ├── skills/
│   ├── commands/
│   ├── agents/
│   └── .mcp.json
├── install/                # OPTIONAL: Installation automation
│   ├── config/             # Configuration files to install
│   └── hooks/              # Lifecycle hook scripts
└── assets/                 # OPTIONAL: Additional resources

3.2 Naming Conventions

Package names MUST adhere to the following rules:

Consist only of lowercase ASCII letters, digits, and hyphens
Begin with a letter (or underscore for internal packages)
Not exceed 64 characters
Not begin with jfn- (reserved for official packages)
Not use reserved names (see Appendix B)

The directory name MUST match the name field in tentacle.yaml with .tentacle appended.

Package Types by Prefix:

Prefix	Type	Example	Description
(none)	Regular	`docker.tentacle`	Standard plugin packages
`_`	Internal	`_core.tentacle`	Internal/system tentacles

Valid examples: docker.tentacle, aws-tools.tentacle, my-utils.tentacle, _core.tentacle

Invalid examples: Docker.tentacle, jfn-core.tentacle, __private.tentacle

3.3 File Naming

Fish function files within a Tentacle MUST use the prefix __tentacle_<package>_ where <package> is the package name with hyphens replaced by underscores. This namespacing prevents conflicts between packages.

Example: For package docker.tentacle, functions MUST be named __tentacle_docker_*.fish.

4. Manifest Specification

4.1 Overview

The manifest file tentacle.yaml is a YAML document describing the package metadata, contents, dependencies, and installation requirements. The manifest MUST be valid YAML 1.2.

4.2 Required Fields

Field	Type	Description
`name`	string	Package name (see §3.2)
`version`	string	Semantic version (see §9)
`description`	string	Brief description (max 256 chars)
`author`	string	Author name or organization
`license`	string	SPDX license identifier

4.3 Optional Fields

Field	Type	Description
`homepage`	string	URL to project homepage
`repository`	string	URL to source repository
`documentation`	string	URL to documentation
`keywords`	string[]	Search keywords (max 10)
`categories`	string[]	Category tags
`fish`	object	Fish layer configuration (see §5)
`jelly`	object	Jelly layer configuration (see §6)
`install`	object	Install layer configuration (see §7)
`requires`	string[]	Package dependencies (see §8)
`conflicts`	string[]	Incompatible packages
`platforms`	string[]	Supported platforms (see §14)
`engines`	object	Runtime version requirements

4.4 Categories

Packages SHOULD specify one or more categories:

devops — Infrastructure and deployment tools
development — Programming language tools
productivity — Workflow and productivity
cloud — Cloud provider tools
database — Database tools
networking — Network utilities
security — Security tools
ai — AI and ML tools
utility — General utilities

4.5 Complete Manifest Example

name: docker
version: 2.0.0
description: Complete Docker development environment with Colima
author: Jelly Labs
license: MIT

homepage: https://github.com/jellylabs/docker.tentacle
repository: https://github.com/jellylabs/docker.tentacle.git

keywords:
  - docker
  - containers
  - colima

categories:
  - devops
  - development

fish:
  functions:
    - fish/__tentacle_docker_*.fish
  init: fish/init.fish
  triggers:
    - char: d
      handler: __tentacle_docker_menu
      description: Docker operations menu
      priority: 100

jelly:
  targets:
    - claude
  skills:
    - jelly/skills/docker-sensei
  commands:
    - jelly/commands/compose.md

install:
  brew:
    - docker
    - colima
  configs:
    ~/.docker/daemon.json: install/config/daemon.json

requires:
  - _core@^1.0.0

platforms:
  - macos
  - linux

engines:
  jfn: ">=1.0.0"
  fish: ">=3.6.0"

5. Fish Layer

5.1 Overview

The Fish layer provides the shell interface for the Tentacle. Every Tentacle MUST include at least one Fish function file.

5.2 Configuration

Field	Type	Required	Description
`functions`	string[]	Yes	Glob patterns for function files
`init`	string	No	Initialization script path
`triggers`	object[]	No	Keyboard trigger definitions
`dependencies`	string[]	No	Required shell commands
`completions`	string	No	Fish completions file path

5.3 Triggers

Triggers define single-character key bindings:

Field	Type	Required	Description
`char`	string	Yes	Single character (printable ASCII)
`handler`	string	Yes	Function name to invoke
`description`	string	Yes	Human-readable description
`priority`	integer	No	Conflict resolution (higher wins)

Reserved trigger characters (cannot be used):

/ — Function search
@ — File picker
# — Memo
! — History
? — Help
> — Directory jump
: — Snippets

6. Jelly Layer

6.1 Overview

The Jelly layer provides AI logic components. Jelly components are Markdown files with YAML frontmatter that define skills, commands, and agents. The Jelly layer is the source format—it gets transformed into provider-specific output during build.

6.2 Configuration

Field	Type	Required	Description
`targets`	string[]	No	AI providers to build for (default: `[claude]`)
`skills`	string[]	No	Skill definition files
`commands`	string[]	No	Command definition files
`agents`	string[]	No	Agent definition files

6.3 Component Types

Skill: Domain expertise applied when relevant topics arise.

Command: Explicit slash commands (e.g., /compose) invoked directly.

Agent: Autonomous workflows that perform multi-step operations.

6.4 Skill Format

Skills MUST use directory format with SKILL.md:

jelly/skills/
└── docker-sensei/
    ├── SKILL.md              # Required
    ├── prompts/              # Optional
    │   ├── question.md
    │   ├── build.md
    │   └── self-improve.md
    └── references/           # Optional

6.5 Build Targets

jelly:
  targets:
    - claude    # generates claude/ directory
    # - gemini  # future

7. Install Layer

7.1 Overview

The install layer automates package manager installations and configuration file deployment.

7.2 Package Manager Support

Field	Type	Description
`brew`	string[]	Homebrew formulae
`cask`	string[]	Homebrew casks
`apt`	string[]	APT packages (Linux)
`npm`	string[]	NPM packages
`pip`	string[]	Python packages
`cargo`	string[]	Rust crates

7.3 Configuration Files

install:
  configs:
    ~/.docker/daemon.json: install/config/daemon.json

7.4 Lifecycle Hooks

install:
  hooks:
    pre: install/hooks/pre-install.fish
    post: install/hooks/post-install.fish

8. Dependency Resolution

8.1 Syntax

Dependencies use the format: package@version-constraint

Constraint	Meaning
`^1.2.3`	Compatible with 1.x.x
`~1.2.3`	Compatible with 1.2.x
`>=1.2.3`	Greater than or equal
`1.2.3`	Exact version

8.2 Resolution Order

Parse all requires from manifest
Resolve version constraints
Check for conflicts
Build dependency graph
Install in topological order

9. Versioning

Tentacles MUST use Semantic Versioning 2.0.0:

MAJOR: Breaking changes
MINOR: New features, backwards compatible
PATCH: Bug fixes, backwards compatible

Pre-release versions: 1.0.0-alpha.1, 1.0.0-beta.2, 1.0.0-rc.1

10. Distribution

10.1 Registry Protocol

Tentacles MAY be distributed via:

Official registry (future)
Git repositories
Direct download (tar.gz)
Object storage (Storj, S3)

10.2 Content Addressing

Distributed packages SHOULD include content hash for verification.

11. Security

11.1 Sandboxing

Tentacles SHOULD declare required permissions.

11.2 Verification

Package integrity via content hash
Author verification via signing (future)

12. Lockfile Format

The tentacle.lock file records exact installed versions:

lockfile_version: 1
packages:
  docker:
    version: 2.0.0
    integrity: sha256-abc123...
    resolved: https://registry.jellyfish.ninja/docker-2.0.0.tar.gz

13. Lifecycle Hooks

Hook	When	Purpose
`pre-install`	Before installation	Validation, backup
`post-install`	After installation	Configuration, setup
`pre-uninstall`	Before removal	Cleanup preparation
`post-uninstall`	After removal	Final cleanup
`pre-update`	Before update	Migration preparation
`post-update`	After update	Migration completion

14. Platform Support

Supported platforms:

macos — macOS (arm64, x86_64)
linux — Linux (various distros)
windows — Windows (WSL)

Platform overrides:

platform_overrides:
  linux:
    install:
      apt:
        - docker.io
      brew: []

15. Examples

Minimal Tentacle

name: hello
version: 1.0.0
description: Hello world tentacle
author: Example
license: MIT

Full Featured Tentacle

See §4.5 for complete manifest example.

16. Plugin Generation

16.1 Claude Plugin Output

When building for Claude, generate:

claude/
├── .claude-plugin/
│   └── plugin.json
├── skills/
├── commands/
└── .mcp.json

16.2 Build Process

Read jelly/ or jelly.md
Transform to target format
Write to <target>/ directory
Generate plugin metadata

Source

Derived from: assets/convos/2-jellfishspec.yaml (lines 1-1500)