Developer Guide

This guide is for developers contributing to AgentPlaybooks or building extensions.

Project Overview

AgentPlaybooks is a platform-independent memory and toolkit for AI agents. It allows users to:

• Create Playbooks - Collections of personas, skills, MCP servers, and memory
• Export in Multiple Formats - JSON, OpenAPI, MCP protocol, Markdown
• Enable AI Write-back - AI agents can update memory via API keys
• Browse Community Repository - Public skills and MCP servers

Technology Stack

Repository Structure

agentplaybooks/
├── docs/                           # Documentation (GitHub + Website)
│   ├── README.md                   # Overview
│   ├── getting-started.md          # Quick start guide
│   ├── architecture.md             # System design
│   ├── api-reference.md            # API documentation
│   ├── mcp-integration.md          # MCP protocol guide
│   ├── skills.md                   # Skills documentation
│   ├── memory.md                   # Memory documentation
│   ├── developer-guide.md          # This file
│   └── self-hosting.md             # Self-hosting guide
│
├── src/
│   ├── app/                        # Next.js App Router
│   │   ├── page.tsx                # Landing page
│   │   ├── layout.tsx              # Root layout
│   │   ├── globals.css             # Global styles
│   │   ├── login/                  # Authentication pages
│   │   │   └── page.tsx            # Login/Register
│   │   ├── dashboard/              # Authenticated user area
│   │   │   ├── page.tsx            # Playbook list
│   │   │   └── playbook/[id]/      # Playbook editor
│   │   ├── explore/                # Public repository
│   │   │   └── page.tsx            # Browse skills/MCPs
│   │   ├── enterprise/             # Enterprise landing
│   │   │   └── page.tsx            # B2B features
│   │   ├── docs/                   # Documentation viewer
│   │   │   └── page.tsx            # MDX renderer
│   │   └── api/                    # API routes (Hono)
│   │       ├── [[...route]]/       # Main API
│   │       │   └── route.ts        # Playbooks, memory, etc.
│   │       ├── mcp/[guid]/         # MCP server endpoints
│   │       │   └── route.ts        # MCP protocol handler
│   │       └── docs/[...slug]/     # Docs API
│   │           └── route.ts        # Serve markdown files
│   │
│   ├── components/                 # React components
│   │   └── ui/                     # UI components
│   │       ├── sidebar.tsx         # Navigation sidebar
│   │       ├── floating-navbar.tsx # Top navigation
│   │       ├── bento-grid.tsx      # Feature grid
│   │       ├── spotlight.tsx       # Spotlight effect
│   │       └── card-hover-effect.tsx
│   │
│   ├── lib/                        # Utilities
│   │   ├── utils.ts                # cn() and helpers
│   │   └── supabase/               # Supabase client
│   │       ├── client.ts           # Browser client
│   │       ├── server.ts           # Server client
│   │       └── types.ts            # Generated types
│   │
│   ├── i18n/                       # Internationalization
│   │   ├── config.ts               # next-intl config
│   │   ├── request.ts              # Locale routing
│   │   └── messages/               # Translation files
│   │       ├── en.json
│   │       ├── hu.json
│   │       ├── de.json
│   │       └── es.json
│   │
│   └── mdx-components.tsx          # Custom MDX components
│
├── supabase/
│   └── migrations/                 # Database migrations
│       └── 20260102_initial_schema.sql
│
├── .github/
│   └── workflows/
│       └── deploy.yml              # CI/CD pipeline
│
├── package.json                    # Dependencies
├── next.config.ts                  # Next.js config
├── tailwind.config.ts              # Tailwind config
├── wrangler.jsonc                  # Cloudflare config
├── open-next.config.ts             # OpenNext config
└── README.md                       # Project README

Development Setup

Prerequisites

• Node.js 20+
• npm 10+
• Git
• Supabase account (free tier OK)
• Cloudflare account (free tier OK)

Local Development

# Clone repository
git clone https://github.com/matebenyovszky/agentplaybooks.git
cd agentplaybooks

# Install dependencies
npm install

# Copy environment template
cp .env.example .env.local

# Edit .env.local with your Supabase credentials
# NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
# NEXT_PUBLIC_SUPABASE_ANON_KEY=xxx
# SUPABASE_SERVICE_ROLE_KEY=xxx

# Run development server
npm run dev

# Open http://localhost:3000

Database Setup

• Create a Supabase project at supabase.com

• Apply supabase/schema.sql in the SQL Editor — that is the whole schema in

one file: types, tables, constraints, indexes, functions, triggers, RLS and policies

• Enable Auth providers (Email, Google, GitHub) in Authentication settings

supabase/schema.sql is a snapshot of the current schema, not a replay of the migrations that produced it, so it is the only file a new project needs. supabase/migrations/ remains the forward history from that snapshot onward — do not apply the older ones on top of it, since the snapshot already contains their result.

The guide used to point at supabase/migrations/20260102_initial_schema.sql. That file never existed in this repository, and neither did any other CREATE TABLE for the core tables — every migration here is incremental, so following the old step against an empty project failed on the first statement.

The schema references auth.users and its policies call auth.uid(), so it

needs the Supabase stack. A bare PostgreSQL server will reject it.

Inspecting the database from an AI editor (optional)

Maintainers can attach the read-only Supabase MCP server, which is how the schema gets inspected without pasting credentials around. Create a .mcp.json in the repo root — it is gitignored, so it stays local:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@0.10.0",
        "--read-only",
        "--project-ref=${SUPABASE_PROJECT_REF}"
      ],
      "env": { "SUPABASE_ACCESS_TOKEN": "${SUPABASE_ACCESS_TOKEN}" }
    }
  }
}

Then set two variables in your shell — never in a committed file:

• SUPABASE_PROJECT_REF — the subdomain of your project URL

(https://.supabase.co)

• SUPABASE_ACCESS_TOKEN — a personal access token from

supabase.com/dashboard/account/tokens

--read-only is deliberate: the token grants account-wide access, so the server should not be able to write. Drop the flag only when you actually intend to apply a migration through it, and put it back afterwards.

Key Concepts

Playbooks

A playbook is a container for:

• Personas - System prompts for AI agents
• Skills - SKILL.md-compatible instructional content
• MCP Servers - Executable federated MCP/OpenAPI connections
• Memory - Key-value storage for context
• API Keys - For write-back authentication
• Secrets Vault - Encrypted credentials for agents (see Secrets Vault)

Secrets Vault

Store encrypted API keys and credentials at the playbook level. Uses AES-256-GCM encryption with per-user derived keys. Agents can use secrets through the use_secret proxy tool without ever seeing plaintext values.

• Secret categories: api_key, password, token, certificate, connection_string, general
• Automatic usage tracking and rotation support
• SSRF protection on the proxy endpoint
• Dashboard UI for managing and revealing secrets

Multi-Format Export

Each playbook can be exported as:

Row Level Security (RLS)

All database access uses Supabase RLS:

• Owners - Full CRUD on their own data
• Editors - Content CRUD on accepted shared playbooks; control-plane fields remain owner-only
• Public playbooks - Read-only access for anyone
• API keys - Validated at API layer, bypass RLS with service role

Development Tasks

Task: Playbook Editor UI ✅ COMPLETED

Goal: Create the UI for editing playbooks

Files created:

src/components/playbook/
├── index.ts              # Barrel export
├── PersonaEditor.tsx     # System prompt editor with auto-save
├── SkillEditor.tsx       # JSON schema editor (visual + raw)
├── McpServerEditor.tsx   # Tools & resources editor
├── MemoryEditor.tsx      # Key-value editor with search
└── ApiKeyManager.tsx     # Generate/revoke API keys

Component Details:

PersonaEditor

• Expandable card with inline name editing
• Auto-resizing textarea for system prompts
• Metadata JSON editor
• Debounced auto-save (1.5s delay)
• Copy to clipboard for prompts
• Delete with confirmation dialog

SkillEditor

• Two view modes: Visual Editor & JSON Schema
• Visual mode: Add/remove parameters, set types, descriptions
• Parameter types: string, number, integer, boolean, array, object
• Required field toggling
• Examples JSON array editor
• Real-time JSON validation with error display

McpServerEditor

• Tabbed interface: Tools | Resources
• Add tools with name, description, inputSchema
• Add resources with URI, name, mimeType
• JSON editors for advanced editing
• Link to MCP documentation

MemoryEditor

• Search/filter memories by key or value
• Add new memory entries
• Edit in modal dialog with JSON validation
• Refresh button for latest data
• Timestamp display (updated_at)

ApiKeyManager

• Permission-based key creation modal
• Available permissions: memory, skills, personas (read/write)
• One-time key display with copy warning
• Key list with prefix and permission badges
• Revoke keys with confirmation

Main Editor Page: src/app/dashboard/playbook/[id]/page.tsx

Features:

• Sticky header with save status indicator
• Tabbed navigation: Personas

  Skills

  MCP

  Memory

  API Keys

  Settings
• Debounced auto-save for playbook settings
• Public/Private toggle in header
• Settings tab with:

- Description textarea - Visibility controls (Private/Public) - All API endpoints with copy buttons - Danger zone for playbook deletion

• Animated tab transitions (Framer Motion)

Demo Mode: src/app/demo/playbook/page.tsx

• Full editor experience without authentication
• localStorage persistence for demo data
• "Demo Mode" banner with sign-up CTA
• Same components as authenticated editor
• Prompt to register when saving

Task: API Endpoints ✅ COMPLETED

Goal: Implement CRUD operations for playbooks

Files:

• src/app/api/[[...route]]/route.ts - Main API file (Hono framework)

Implemented Endpoints:

// Playbooks (JWT auth required for mutations)
GET    /api/playbooks              // List user's playbooks
POST   /api/playbooks              // Create playbook
GET    /api/playbooks/:guid        // Get playbook (public or owned) + format param
PUT    /api/playbooks/:id          // Update playbook
DELETE /api/playbooks/:id          // Delete playbook

// Personas (JWT auth required)
GET    /api/playbooks/:id/personas
POST   /api/playbooks/:id/personas
PUT    /api/playbooks/:id/personas/:pid
DELETE /api/playbooks/:id/personas/:pid

// Skills (JWT auth required)
GET    /api/playbooks/:id/skills
POST   /api/playbooks/:id/skills
PUT    /api/playbooks/:id/skills/:sid
DELETE /api/playbooks/:id/skills/:sid

// Memory (API key or JWT for writes)
GET    /api/playbooks/:guid/memory          // Public read for public playbooks
PUT    /api/playbooks/:guid/memory/:key     // Requires API key or owner
DELETE /api/playbooks/:guid/memory/:key     // Requires API key or owner

// API Keys (JWT auth, owner only)
GET    /api/playbooks/:id/api-keys
POST   /api/playbooks/:id/api-keys          // Returns plain key ONCE
DELETE /api/playbooks/:id/api-keys/:kid

// Collaboration (owner-managed, JWT session only)
GET    /api/playbooks/:id/collaborators
POST   /api/playbooks/:id/collaborators
DELETE /api/playbooks/:id/collaborators/:collaboratorId
GET    /api/collaboration-invites/:token
POST   /api/collaboration-invites/:token

// Public Repository
GET    /api/public/skills
GET    /api/public/skills/:id
GET    /api/public/mcp
GET    /api/public/mcp/:id

// Health Check
GET    /api/health

Format Parameter:

The GET /api/playbooks/:guid endpoint supports multiple output formats:

Authentication Flow:

• JWT Auth - For dashboard/management (from Supabase session)
• API Key Auth - For AI agent write-back (Bearer apb_live_xxx)
• Public Access - No auth needed for public playbook reads

Key Implementation Details:

• Uses getServiceSupabase() to bypass RLS where needed
• API keys stored as SHA-256 hash, validated against hash
• Ownership checked before all mutations

Testing

# Run linter
npm run lint

# Run application and CLI tests
npm run test:all

# Type check
npx tsc --noEmit

# Build for production
npm run build

Deployment

Deployment is automatic via GitHub Actions:

• Push to main branch
• GitHub Actions builds the project
• Deploys to Cloudflare Pages

Manual deployment:

npm run build
npx wrangler pages deploy .open-next

Code Style

• TypeScript - Strict mode enabled
• Functional components - No class components
• Tailwind - No custom CSS unless necessary
• Server Components - Default, use 'use client' only when needed
• Naming - camelCase for variables, PascalCase for components

Contributing

• Fork the repository
• Create a feature branch (git checkout -b feature/amazing-feature)
• Commit changes (git commit -m 'feat: add amazing feature')
• Push to branch (git push origin feature/amazing-feature)
• Open a Pull Request

Resources

• Next.js Documentation
• Supabase Documentation
• Cloudflare Pages Documentation
• Hono Documentation
• Aceternity UI Components
• Anthropic Tool Use
• MCP Specification

Documentation Freshness Checklist

Use this checklist when changing APIs or MCP behavior:

• Update README.md endpoint summaries.
• Update public/docs/api-reference.md with request/response shape changes.
• Update public/docs/mcp-integration.md when tools/resources or MCP flows change.
• Add at least one concrete example for the new behavior.
• Validate examples against real route handlers before merging.

For agent quality, prefer docs that are:

• Current (match shipped behavior)
• Targeted (short task-oriented examples)
• Self-improving (encourage write-back of discovered constraints to memory/canvas)