Proposal: Pack Plugin Architecture

[madeinoz67]

Hey all, as Ive been developing a few packs over the last week and Ive quickly realised that this is going to be come a problem to maintain if third party packs are kept in the main repo.

Therefore I want to open up for discussion for a Pack Plugin in Architecture and have attach a possible solution for review and discussion. But main point is opening up the current architect for discussion such that it can be easily maintained as the project gains momentum.

PAI Plugin Architecture Proposal

Version: 0.1.0 (Draft)
Date: 2026-01-12
Status: Proposal - Awaiting Review

---

Executive Summary

This document proposes a plugin architecture for Personal AI Infrastructure (PAI) that enables third-party developers to create, distribute, and maintain packs independently of the main project repository. The goal is to shift from a "merge-to-main" model to a "publish-and-install" model while preserving the AI-first, markdown-centric design philosophy that makes PAI unique.

---

1. Problem Statement

Current Architecture Limitations

The existing pack system has several constraints that limit ecosystem growth:

Issue	Impact
Monolithic Repository	All packs live in Packs/ within the main repo
PR-Based Contribution	Third-party developers must submit PRs to add packs
Maintainer Burden	Project owner must review, merge, and maintain all packs
Version Coupling	Pack versions tied to main project releases
Limited Discoverability	No registry or catalog for finding community packs
No Independent Lifecycle	Packs cannot be released, updated, or deprecated independently
Support Responsibility	Project owner implicitly responsible for all pack support

The Pack Support Problem

When packs are merged into the main repository, support expectations become unclear:

┌─────────────────────────────────────────────────────────────────┐
│                   CURRENT SUPPORT BURDEN                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   User encounters issue with third-party pack                   │
│                        │                                        │
│                        ▼                                        │
│   Opens issue on main PAI repository                            │
│                        │                                        │
│                        ▼                                        │
│   Project owner must:                                           │
│   • Triage the issue                                            │
│   • Determine if it's pack-specific or core                     │
│   • Contact original pack author (if reachable)                 │
│   • Fix it themselves OR close as "won't fix"                   │
│                        │                                        │
│                        ▼                                        │
│   Result: Owner becomes de facto maintainer of ALL packs        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Specific Support Challenges:

Challenge	Description
Abandoned Packs	Original author stops maintaining; pack rots over time
Breaking Changes	PAI core updates break third-party packs; who fixes them?
Bug Attribution	Users can't distinguish pack bugs from core bugs
Quality Variance	No minimum quality standard; poor packs reflect on PAI
Documentation Debt	Incomplete docs create support tickets for project owner
Compatibility Matrix	Which pack versions work with which PAI versions?
Security Incidents	Vulnerable pack code becomes project owner's liability
Response Time	Users expect timely support regardless of pack origin

Desired State

┌─────────────────────────────────────────────────────────────────┐
│                     CURRENT MODEL                               │
│                                                                 │
│   Third Party → PR → Review → Merge → Release                   │
│                 ↓                                               │
│         Project Owner (bottleneck)                              │
└─────────────────────────────────────────────────────────────────┘

                          ↓ Transform to ↓

┌─────────────────────────────────────────────────────────────────┐
│                     PROPOSED MODEL                              │
│                                                                 │
│   Third Party → Implement API → Publish → Users Install         │
│                                                                 │
│   Project Owner: Maintains core + API contract only             │
│   Community: Builds, publishes, maintains their own packs       │
└─────────────────────────────────────────────────────────────────┘

---

2. Design Principles

Building on PAI's existing philosophy, the plugin architecture should follow these principles:

2.1 AI-First Design

• Packs remain markdown-centric with YAML frontmatter
• Installation continues via INSTALL.md wizard pattern
• Discovery uses natural language triggers (SKILL.md)
• No complex configuration DSLs or registries

2.2 Self-Contained Autonomy

• Each pack is a complete, independent unit
• Packs include all code, docs, and assets
• No implicit dependencies on main repo internals
• Clear API boundaries

2.3 Progressive Complexity

• Simple packs: single directory, copy to install
• Complex packs: npm package with CLI installer
• Advanced packs: MCP server with runtime integration

2.4 Trust but Verify

• Community packs are user's responsibility
• Official packs have verified status
• Security scanning recommendations, not enforcement
• VERIFY.md checklist remains mandatory

---

3. Proposed Architecture

3.1 Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                         PAI PLUGIN ARCHITECTURE                     │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────────┐  │
│  │   OFFICIAL   │    │  COMMUNITY   │    │    PRIVATE/LOCAL     │  │
│  │    PACKS     │    │    PACKS     │    │       PACKS          │  │
│  │              │    │              │    │                      │  │
│  │  pai-*/      │    │  @user/pack  │    │  ~/my-packs/         │  │
│  │  (verified)  │    │  (npm/git)   │    │  (local dev)         │  │
│  └──────┬───────┘    └──────┬───────┘    └──────────┬───────────┘  │
│         │                   │                       │              │
│         └───────────────────┴───────────────────────┘              │
│                             │                                       │
│                    ┌────────▼────────┐                             │
│                    │  PACK RESOLVER  │                             │
│                    │                 │                             │
│                    │  - Discovery    │                             │
│                    │  - Validation   │                             │
│                    │  - Installation │                             │
│                    └────────┬────────┘                             │
│                             │                                       │
│                    ┌────────▼────────┐                             │
│                    │   PLUGIN API    │                             │
│                    │                 │                             │
│                    │  - Pack Schema  │                             │
│                    │  - Skill API    │                             │
│                    │  - Hook API     │                             │
│                    │  - Tool API     │                             │
│                    └────────┬────────┘                             │
│                             │                                       │
│                    ┌────────▼────────┐                             │
│                    │   PAI RUNTIME   │                             │
│                    │                 │                             │
│                    │  - Claude Code  │                             │
│                    │  - Hook System  │                             │
│                    │  - MCP Servers  │                             │
│                    └─────────────────┘                             │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

3.2 Pack Distribution Channels

Channel 1: Official Packs (pai-*)

• Maintained in main repository
• Verified and tested
• Reference implementations
• Bundled with PAI releases

Channel 2: Community Packs (npm/GitHub)

• Published to npm as @pai-community/<pack-name> or individual namespaces
• Installable via bun add or direct git clone
• Listed in community registry (opt-in)
• Author-maintained

Channel 3: Private/Local Packs

• Local development or proprietary packs
• Not published anywhere
• Installed via file path
• Organization-specific

3.3 Pack Manifest Evolution

The current README.md metadata evolves to a formal pack.json:

{
  "$schema": "https://pai.dev/schemas/pack/v1.json",
  "name": "pai-example-skill",
  "version": "1.0.0",
  "description": "Example skill pack for PAI",
  "author": "developer@example.com",
  "license": "MIT",

  "pack": {
    "type": "skill",
    "apiVersion": "1.0",
    "platform": "claude-code",

    "icon": "assets/icon.png",

    "entry": {
      "skill": "src/skills/example/SKILL.md",
      "install": "INSTALL.md",
      "verify": "VERIFY.md"
    },

    "directories": {
      "docs": "docs/",
      "examples": "examples/",
      "assets": "assets/"
    },

    "capabilities": {
      "skills": ["example"],
      "hooks": ["PostToolUse"],
      "tools": ["example-tool"],
      "mcpServers": []
    },

    "dependencies": {
      "packs": {
        "pai-agents-skill": "^1.0.0",
        "pai-knowledge-system": "^1.0.0"
      },
      "npm": {
        "zod": "^3.0.0"
      }
    },

    "repository": {
      "type": "git",
      "url": "https://github.com/user/pai-example-skill"
    },

    "keywords": ["osint", "investigation"],

    "verified": false,
    "deprecated": false
  }
}

---

4. Plugin API Contract

4.1 API Versioning

API Version: MAJOR.MINOR

MAJOR: Breaking changes (existing packs may not work)
MINOR: Backwards-compatible additions (new capabilities)

Example: apiVersion "1.0" works with PAI runtime 1.0.x, 1.1.x, etc.
         apiVersion "2.0" requires PAI runtime 2.x

4.2 Skill API Contract

Skills must provide a SKILL.md with this structure:

---
# Required fields
name: string           # Unique skill identifier
description: string    # When to use this skill
triggers: string[]     # Natural language activation phrases

# Optional fields
version: string        # Skill version (defaults to pack version)
author: string         # Skill author
dependencies: string[] # Required skill names
---

# {name}

[Skill documentation in markdown]

## Invocation
[How the skill is triggered]

## Workflows
[Available workflows and their purposes]

## Agent Configuration
[Trait mappings for different workflows]

4.3 Workflow API Contract

Workflows must follow this structure:

---
name: WorkflowName
version: string
description: string
triggers: string[]
scope: targeted | comprehensive | deep
---

# {WorkflowName}

## Purpose
[What this workflow accomplishes]

## Prerequisites
[Required setup, permissions, or context]

## Steps
[Numbered execution steps]

## Agent Roles
[Table mapping roles to traits]

## Output Format
[Expected output structure]

## Error Handling
[Recovery procedures]

## Knowledge Storage
[How results are persisted]

4.4 Hook API Contract

Hooks must export specific functions based on event type:

// Hook Interface
interface HookModule {
  // Called during installation
  install?: () => Promise<void>;

  // Called during uninstallation
  uninstall?: () => Promise<void>;

  // Event handler (name matches event)
  handler: (context: HookContext) => Promise<HookResult>;
}

interface HookContext {
  event: string;          // Event name
  tool?: string;          // Tool name (for tool events)
  input?: unknown;        // Event input data
  output?: unknown;       // Event output data (post events)
  session: SessionContext;
}

interface HookResult {
  continue: boolean;      // Whether to proceed
  modified?: unknown;     // Modified data (if any)
  message?: string;       // User-facing message
}

4.5 Tool API Contract

Tools must be TypeScript files with:

// Tool Interface
interface ToolModule {
  name: string;
  description: string;

  // JSON Schema for parameters
  parameters: JSONSchema;

  // Execution function
  execute: (params: unknown) => Promise<ToolResult>;
}

interface ToolResult {
  success: boolean;
  output: unknown;
  error?: string;
}

4.6 MCP Server Contract

MCP servers follow the standard MCP protocol with PAI-specific metadata:

{
  "name": "pai-example-mcp",
  "version": "1.0.0",
  "protocol": "mcp",
  "transport": "stdio",
  "command": "bun",
  "args": ["run", "src/mcp/server.ts"],

  "tools": [
    {
      "name": "example_tool",
      "description": "Does something",
      "inputSchema": { ... }
    }
  ],

  "resources": [
    {
      "uri": "example://resource",
      "name": "Example Resource"
    }
  ]
}

---

5. Pack Resolution & Installation

5.1 Resolution Flow

User Request: "Install @user/cool-pack"
                    │
                    ▼
┌─────────────────────────────────────┐
│           PACK RESOLVER             │
├─────────────────────────────────────┤
│ 1. Parse pack identifier            │
│    - npm: @scope/name               │
│    - git: github:user/repo          │
│    - local: file:/path/to/pack      │
│    - official: pai-name             │
├─────────────────────────────────────┤
│ 2. Fetch pack manifest              │
│    - Download pack.json             │
│    - Validate against schema        │
│    - Check API version compatibility│
├─────────────────────────────────────┤
│ 3. Resolve dependencies             │
│    - Build dependency tree          │
│    - Check for conflicts            │
│    - Determine install order        │
├─────────────────────────────────────┤
│ 4. Execute installation             │
│    - Install pack dependencies first│
│    - Run pack's INSTALL.md wizard   │
│    - Execute install hooks          │
│    - Register skills/tools/hooks    │
├─────────────────────────────────────┤
│ 5. Verify installation              │
│    - Run VERIFY.md checklist        │
│    - Report status                  │
└─────────────────────────────────────┘

5.2 Installation Commands

# Install from npm
pai install @user/cool-pack

# Install from GitHub
pai install github:user/pai-cool-pack

# Install from local path
pai install file:./my-local-pack

# Install official pack
pai install pai-osint-skill

# Install specific version
pai install @user/cool-pack@1.2.0

# Install with dependencies
pai install @user/cool-pack --with-deps

# Dry-run (show what would be installed)
pai install @user/cool-pack --dry-run

5.3 Pack Registry (Optional)

A lightweight registry for discovery:

┌─────────────────────────────────────────────────────────────────┐
│                    PAI PACK REGISTRY                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Registry Types:                                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │  OFFICIAL   │  │  COMMUNITY  │  │  PRIVATE (self-hosted)  │ │
│  │  registry   │  │  registry   │  │  registry               │ │
│  │             │  │             │  │                         │ │
│  │ pai.dev/    │  │ Opt-in via  │  │ Organization-specific   │ │
│  │ registry    │  │ pack.json   │  │ npm registry            │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
│                                                                 │
│  Registry Entry:                                                │
│  {                                                              │
│    "name": "pai-cool-skill",                                    │
│    "version": "1.2.0",                                          │
│    "description": "Does cool things",                           │
│    "author": "user",                                            │
│    "downloads": 1234,                                           │
│    "verified": false,                                           │
│    "source": "npm:@user/pai-cool-skill",                        │
│    "keywords": ["cool", "skill"],                               │
│    "apiVersion": "1.0"                                          │
│  }                                                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

5.4 Registry-Free Installation

The registry is optional. Packs can be installed directly via:

• npm package name
• Git repository URL
• Local file path
• Direct download URL

This preserves the "no central authority" philosophy while enabling discoverability for those who want it.

---

6. Dependency Management

6.1 Dependency Types

dependencies:
  # PAI pack dependencies
  packs:
    pai-agents-skill: "^1.0.0"     # Semver range
    pai-knowledge-system: ">=1.0"  # Minimum version

  # npm package dependencies
  npm:
    zod: "^3.0.0"
    axios: "^1.0.0"

  # Optional dependencies (enhanced functionality)
  optional:
    pai-browser-skill: "^1.0.0"

  # Peer dependencies (user must install separately)
  peer:
    pai-core-install: "^1.0.0"

6.2 Dependency Resolution Strategy

Strategy: Flat with Conflict Detection

1. Build complete dependency tree
2. Flatten to single level
3. Detect version conflicts
4. If conflict:
   - Use highest compatible version if possible
   - Error with clear message if incompatible
5. Install in topological order (dependencies first)

6.3 Lock File

// pai-lock.json
{
  "lockVersion": 1,
  "resolved": {
    "pai-agents-skill": {
      "version": "1.2.3",
      "source": "npm:@pai/agents-skill@1.2.3",
      "integrity": "sha512-...",
      "dependencies": {
        "pai-core-install": "1.0.0"
      }
    }
  }
}

---

7. Security Considerations

7.1 Trust Model

┌────────────────────────────────────────────────────────────────┐
│                      TRUST LEVELS                              │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│  🟢 OFFICIAL (Highest Trust)                                   │
│     - Packs in main PAI repository                             │
│     - Reviewed by maintainers                                  │
│     - Signed releases                                          │
│                                                                │
│  🟡 VERIFIED (Medium Trust)                                    │
│     - Community packs that passed review                       │
│     - Listed in official registry                              │
│     - Author identity verified                                 │
│                                                                │
│  🟠 COMMUNITY (User Discretion)                                │
│     - Any published pack                                       │
│     - No review required                                       │
│     - User assumes responsibility                              │
│                                                                │
│  🔴 LOCAL (No Trust Assertion)                                 │
│     - Locally developed packs                                  │
│     - Not published                                            │
│     - Developer responsibility                                 │
│                                                                │
└────────────────────────────────────────────────────────────────┘

7.2 Security Scanning Recommendations

# .pai-security.yml (optional)
scan:
  # Check for secrets in code
  secrets: true

  # Check npm dependencies for vulnerabilities
  npm_audit: true

  # Check for dangerous patterns
  patterns:
    - eval(
    - Function(
    - child_process
    - fs.writeFileSync (outside pack dir)

  # Allowed patterns (whitelist)
  allowed:
    - fs.readFileSync
    - path.join

7.3 Sandboxing Considerations

For untrusted packs, consider:

• Running tools in isolated processes
• Filesystem access restrictions
• Network access controls
• Resource limits (CPU, memory, time)

Note: Full sandboxing is complex and may be a future enhancement.

---

8. Pack Development Experience

8.1 Pack Scaffolding

# Create new skill pack
pai create-pack my-skill --type=skill

# Create new system pack
pai create-pack my-system --type=system

# Create from template
pai create-pack my-pack --template=osint-skill

Generated structure:

my-skill/
├── pack.json           # Pack manifest (required)
├── README.md           # Overview documentation (required)
├── INSTALL.md          # Installation wizard (required)
├── VERIFY.md           # Verification checklist (required)
├── CHANGELOG.md        # Version history (required)
│
├── assets/             # Static assets (required)
│   ├── icon.png        # Pack icon - 256x256 transparent PNG (required)
│   ├── banner.png      # Optional banner image for registry
│   └── screenshots/    # Screenshots for documentation
│       └── demo.png
│
├── docs/               # Extended documentation (required)
│   ├── QUICK_REFERENCE.md    # Quick start guide
│   ├── USER_GUIDE.md         # Comprehensive usage guide
│   ├── API.md                # API documentation (if applicable)
│   ├── TROUBLESHOOTING.md    # Common issues and solutions
│   └── CONTRIBUTING.md       # Contribution guidelines
│
├── examples/           # Usage examples (required)
│   ├── basic/          # Basic usage examples
│   │   └── example-usage.md
│   ├── advanced/       # Advanced scenarios
│   │   └── complex-workflow.md
│   └── integrations/   # Integration examples with other packs
│       └── with-knowledge-system.md
│
├── src/                # Source code
│   ├── skills/
│   │   └── my-skill/
│   │       ├── SKILL.md
│   │       └── Workflows/
│   │           └── ExampleWorkflow.md
│   └── tools/          # TypeScript tools
│       └── my-tool.ts
│
├── config/             # Configuration templates
│   └── settings-hooks.json
│
└── tests/              # Test files
    └── skill.test.ts

8.1.1 Directory Requirements

assets/ - Static Assets (Required)

Contains all static files for the pack including the mandatory icon.

File	Required	Description
icon.png	Yes	Pack icon (256x256 transparent PNG)
banner.png	No	Registry banner (1280x640 recommended)
screenshots/	No	Screenshots for documentation
diagrams/	No	Architecture and flow diagrams

docs/ - Extended Documentation (Required)

Contains comprehensive documentation beyond the root README.md.

File	Required	Description
QUICK_REFERENCE.md	Yes	Concise quick-start guide
USER_GUIDE.md	Yes	Comprehensive usage documentation
API.md	Conditional	Required if pack exposes APIs or tools
TROUBLESHOOTING.md	Recommended	Common issues and solutions
CONTRIBUTING.md	Recommended	How to contribute to the pack

examples/ - Usage Examples (Required)

Contains runnable examples demonstrating pack capabilities.

Directory	Required	Description
basic/	Yes	Simple, introductory examples
advanced/	Recommended	Complex or multi-step scenarios
integrations/	Recommended	Examples with other PAI packs

Example Format:

• Markdown files (.md) with step-by-step instructions
• Code files with inline comments
• Self-contained scenarios that users can follow

8.2 Development Workflow

# Link pack for local development
pai link ./my-skill

# Watch for changes and auto-reload
pai dev ./my-skill

# Validate pack structure
pai validate ./my-skill

# Run pack tests
pai test ./my-skill

# Build for distribution
pai build ./my-skill

# Publish to npm
pai publish ./my-skill

8.3 Pack Validation

$ pai validate ./my-skill

Pack Structure
  ✓ pack.json valid
  ✓ API version 1.0 compatible
  ✓ README.md present with required sections
  ✓ INSTALL.md present
  ✓ VERIFY.md checklist present
  ✓ CHANGELOG.md present

Icon & Assets
  ✓ assets/icon.png exists
  ✓ Icon dimensions: 256x256
  ✓ Icon format: PNG with transparency
  ✓ Icon size: 42 KB (< 100 KB limit)

Documentation
  ✓ docs/ directory exists
  ✓ docs/QUICK_REFERENCE.md present
  ✓ docs/USER_GUIDE.md present
  ✗ docs/TROUBLESHOOTING.md missing

Examples
  ✓ examples/ directory exists
  ✓ examples/basic/ contains at least 1 example
  ⚠ examples/advanced/ is empty (recommended)

Skill Definition
  ✓ SKILL.md has required fields
  ✓ All workflows have required sections
  ✓ Triggers array is non-empty

Dependencies
  ✓ Dependencies resolvable
  ✓ No circular dependencies

Security
  ✓ No secrets detected
  ✓ No dangerous patterns found

Summary: 1 error, 1 warning

---

9. Migration Strategy

9.1 Phase 1: API Formalization (Non-Breaking)

• Document current implicit API as formal contracts
• Add pack.json to existing packs (alongside README metadata)
• Create validation tooling
• No changes to existing behavior

9.2 Phase 2: Resolution Infrastructure

• Implement Pack Resolver
• Support multiple distribution channels
• Add pai install command
• Existing directory-based discovery continues working

9.3 Phase 3: Community Enablement

• Publish pack development guide
• Create pack templates
• Launch community registry (opt-in)
• Official packs remain in main repo

9.4 Phase 4: Full Independence

• Community packs fully independent
• Main repo contains only core + official packs
• Community maintains their own packs
• Project owner burden reduced

9.5 Backwards Compatibility

Guarantee:
- Packs using current structure continue to work
- pack.json is additive (README.md metadata still valid)
- No forced migration for existing packs
- Gradual opt-in to new features

---

10. Comparison with Other Systems

Aspect	VSCode Extensions	npm Packages	PAI Packs (Proposed)
Manifest	package.json	package.json	pack.json + SKILL.md
Discovery	Marketplace	npmjs.com	Optional registry + direct install
Installation	GUI/CLI	CLI	AI-guided wizard
Activation	Events	Import	Natural language triggers
Isolation	Extension host	None	Optional sandboxing
Configuration	JSON settings	package.json	Markdown + env vars
Documentation	Separate	README	Single markdown files
AI-Optimized	No	No	Yes

---

11. Open Questions

11.1 Registry Hosting

• Should there be an official community registry?
• Self-hosted vs. cloud-hosted?
• Who moderates/maintains?

11.2 Verification Process

• What does "verified" mean for community packs?
• Who performs verification?
• Automated vs. manual review?

11.3 Breaking Changes

• How to handle API version upgrades?
• Migration tooling for pack authors?
• Deprecation timeline?

11.4 Monetization (Future)

• Should paid packs be supported?
• Licensing enforcement?
• Revenue sharing?

11.5 Pack Signing

• Digital signatures for authenticity?
• Certificate authority?
• Trust chain?

---

12. Implementation Estimate

Phase	Components	Effort
Phase 1	API docs, pack.json schema, validation	Small
Phase 2	Pack resolver, multi-source install	Medium
Phase 3	Dev tools, templates, registry	Medium
Phase 4	Community migration, docs	Small

---

13. References

Plugin Architecture Patterns

• Software Architecture Patterns Guide - Overview of microkernel/plugin patterns
• Plugin Architecture - dotCMS - Building flexible and scalable applications
• Plugin Decoupling Best Practices - ArjanCodes

TypeScript Plugin Systems

• JavaScript Plugin Architecture with TypeScript - Reference implementation
• Build a Plugin System with Node.js - Practical guide
• Designing Plugin Systems in TypeScript - Type-safe patterns

VSCode Extension Architecture

• VSCode Extension Anatomy - Official documentation
• VSCode Architecture Overview - Extension host model
• Patterns and Principles - API design patterns

---

Appendix A: Full pack.json Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["name", "version", "description", "pack"],
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^[a-z0-9-]+$",
      "description": "Pack identifier (lowercase, hyphens only)"
    },
    "version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+$",
      "description": "Semantic version (MAJOR.MINOR.PATCH)"
    },
    "description": {
      "type": "string",
      "description": "Brief description of what the pack does"
    },
    "author": {
      "type": "string",
      "description": "Author name or email"
    },
    "license": {
      "type": "string",
      "description": "SPDX license identifier"
    },
    "pack": {
      "type": "object",
      "required": ["type", "apiVersion", "platform", "icon", "entry", "directories"],
      "properties": {
        "type": {
          "enum": ["skill", "system", "tool", "mcp"],
          "description": "Pack type classification"
        },
        "apiVersion": {
          "type": "string",
          "pattern": "^\\d+\\.\\d+$",
          "description": "PAI Plugin API version compatibility"
        },
        "platform": {
          "enum": ["claude-code"],
          "description": "Target platform"
        },
        "icon": {
          "type": "string",
          "description": "Path to pack icon (256x256 transparent PNG)",
          "pattern": "^assets/icon\\.png$"
        },
        "entry": {
          "type": "object",
          "required": ["install", "verify"],
          "properties": {
            "skill": {
              "type": "string",
              "description": "Path to SKILL.md (required for skill packs)"
            },
            "install": {
              "type": "string",
              "description": "Path to INSTALL.md wizard"
            },
            "verify": {
              "type": "string",
              "description": "Path to VERIFY.md checklist"
            }
          }
        },
        "directories": {
          "type": "object",
          "required": ["docs", "examples", "assets"],
          "properties": {
            "docs": {
              "type": "string",
              "description": "Path to documentation directory"
            },
            "examples": {
              "type": "string",
              "description": "Path to examples directory"
            },
            "assets": {
              "type": "string",
              "description": "Path to assets directory"
            }
          }
        },
        "capabilities": {
          "type": "object",
          "properties": {
            "skills": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Skill identifiers provided by this pack"
            },
            "hooks": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Hook event types this pack registers"
            },
            "tools": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Tool names provided by this pack"
            },
            "mcpServers": {
              "type": "array",
              "items": { "type": "string" },
              "description": "MCP server names provided by this pack"
            }
          }
        },
        "dependencies": {
          "type": "object",
          "properties": {
            "packs": {
              "type": "object",
              "description": "Required PAI pack dependencies with semver ranges"
            },
            "npm": {
              "type": "object",
              "description": "Required npm package dependencies"
            },
            "optional": {
              "type": "object",
              "description": "Optional dependencies for enhanced functionality"
            },
            "peer": {
              "type": "object",
              "description": "Peer dependencies user must install separately"
            }
          }
        },
        "repository": {
          "type": "object",
          "properties": {
            "type": { "type": "string" },
            "url": { "type": "string", "format": "uri" }
          },
          "description": "Source repository information"
        },
        "keywords": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Search keywords for registry discovery"
        },
        "verified": {
          "type": "boolean",
          "description": "Whether pack has been verified by PAI maintainers"
        },
        "deprecated": {
          "type": "boolean",
          "description": "Whether pack is deprecated"
        }
      }
    }
  }
}

---

Appendix B: Icon Specification

Requirements

Property	Requirement
Format	PNG with transparency
Dimensions	256 x 256 pixels (exact)
Location	assets/icon.png (mandatory path)
Color Space	sRGB
Bit Depth	8-bit or 16-bit
Max File Size	100 KB

Design Guidelines

┌─────────────────────────────────────────────────────────────────┐
│                      ICON DESIGN GUIDELINES                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  DO:                                                            │
│  ✓ Use simple, recognizable shapes                              │
│  ✓ Ensure visibility at 32x32 (registry thumbnail)              │
│  ✓ Use transparent background                                   │
│  ✓ Center the design with ~10% padding                          │
│  ✓ Use consistent stroke weight (2-4px at 256px)                │
│  ✓ Test against light and dark backgrounds                      │
│                                                                 │
│  DON'T:                                                         │
│  ✗ Include text (illegible at small sizes)                      │
│  ✗ Use gradients that don't scale well                          │
│  ✗ Use thin lines (<2px at 256px)                               │
│  ✗ Include version numbers or dates                             │
│  ✗ Copy existing PAI official pack icons                        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Icon Validation

The pai validate command checks:

• File exists at assets/icon.png
• Dimensions are exactly 256x256
• Format is PNG with transparency
• File size under 100 KB

Optional Assets

Asset	Path	Purpose
Banner	assets/banner.png	Registry listing (1280x640 recommended)
Screenshots	assets/screenshots/*.png	Documentation visuals
Diagrams	assets/diagrams/*.png	Architecture/flow diagrams

---

Appendix C: CLI Command Reference

# Pack Management
pai install <pack>           # Install a pack
pai uninstall <pack>         # Remove a pack
pai update <pack>            # Update to latest version
pai list                     # List installed packs
pai search <query>           # Search registry
pai info <pack>              # Show pack details

# Development
pai create-pack <name>       # Scaffold new pack
pai link <path>              # Link local pack for dev
pai unlink <pack>            # Unlink local pack
pai dev <path>               # Development mode with watch
pai validate <path>          # Validate pack structure
pai test <path>              # Run pack tests
pai build <path>             # Build for distribution
pai publish <path>           # Publish to npm

# Registry
pai login                    # Authenticate with registry
pai logout                   # Clear authentication
pai whoami                   # Show current user
pai star <pack>              # Star a pack
pai unstar <pack>            # Unstar a pack

---

End of Proposal

This document is a living proposal. Feedback and contributions welcome.

[virtualian]

This is excellent, well-constructed and timely; I'm working on a (personal) Pack now and thinking along the same lines. I suspect @danielmiessler has thought about this too and will opine soon.

I'll review and comment in more detail when I can make time in my projects.

In the meantime, some immediate reactions...

• It is imperative to avoid the Node.js package/module mess and the recent malicious injections into it (search for PhantomRaven, Shai-Hulud, S1ngularity, Vidar Info-Stealer Campaign). Given Daniel's security experience, I'm confident he'll have ideas.
• A PAI CLI (pai) is a great concept for packs, but could be used for other PAI 'things' too, so make pack a sub-command, i.e. pai pack, and thus pai pack install, pai pack update, pai pack list, pai pack search, ...

[madeinoz67]

Thanks @virtualian I totally agree with you on the NPM risk side

I like the idea of the cli doing other PAI related 'things' and makes sense

[danielmiessler]

This looks extraordinary. I'm going to have Kai look at this after we do this next release to see if we can modify the official PAI Pack system to use a system like this.

I still need some help figuring out what is different from the current system, but I'm sure that will become clear as I read it deeper and have Kai find the differences.

Thank you!

[madeinoz67]

@danielmiessler I guess the main difference is not much, not a lot has to change in the packs, what it does is to define a way to decouple pack hosting from the main project repo in a manner where they can be hosted and supported externally or in a central community repository if so required but aligns their dependencies with the core system, or other packs.

[madeinoz67]

Actually this would make a great vid ;) on how you go about it using pai and fabric workflows etc

[danielmiessler]

Packs are now the core architecture in v3.0 — they're the modular, installable unit of PAI functionality. The Pack system is live and ships with the repo. See the Packs/ directory and the v3.0 release notes for details.