431 lines (323 loc) · 16.1 KB

PCL Documentation Index

Complete guide to all PCL documentation, organized by topic and phase.

🚀 Getting Started

New Users

Getting Started Guide (Current Features) - Start here!
README.md - Project overview and quick start
Installation Guide - Setup instructions

Core Concepts

PCL Specification v1 - Official language specification (RFC-style)
Language Grammar - Formal grammar definition
Type System - Type system documentation

📚 Phase 1: Core Language (100% Complete)

Parser & Compiler

Parser Documentation - Parser API and usage
Semantic Analyzer - Type checking and analysis
AST Reference - Abstract Syntax Tree nodes
Code Generation - Code generation to various formats

Runtime & Execution

Runtime Documentation - Runtime system overview
Provider System - LLM provider architecture
Expression Evaluator - Expression evaluation

Registry System

Registry Architecture - Multi-backend registry
Backend Comparison - Memory, JSON, SQLite, PostgreSQL
Search & Indexing - Full-text search

CLI Commands

CLI Reference - Command-line interface
Registry Commands - 7 registry commands

Phase 1 Completion

Phase 1.2-1.4 Complete - Registry completion summary

💻 Phase 2.1: IDE Support (100% Complete)

Language Server Protocol

LSP Overview - Complete LSP implementation summary
Server Architecture - LSP server design
Provider System - Individual providers

LSP Features

Diagnostics - Real-time error detection
Completion - IntelliSense with 26 keywords, 13 snippets
Hover - Documentation on hover (30+ properties)
Definition - Go to definition (Ctrl+Click)
References - Find all references
Symbols - Document outline
Formatting - Auto-format code

VSCode Extension

Extension README - VSCode extension documentation
Installation Guide - Setup instructions
Features Guide - What the extension provides

Phase Completion Documents

Phase 2.1 Complete - Full phase summary (700 lines)
Day 1-2 Complete - Server scaffold
Day 3-5 Complete - Document manager
Day 6-8 Complete - Diagnostics
Day 11-13 Complete - Completion
Day 14-15 Complete - Hover

🎯 Phase 2.2: Skills Ecosystem (100% Complete)

Skills Overview

Skills Ecosystem Complete - Full phase summary (700 lines)
Claude Code Compatibility - Claude Code integration guide (2,800 lines)
Agent Skills Compatibility - agentskills.io integration (1,500 lines)

🛠️ Phase 2.3: Skills CLI (100% Complete)

Skills CLI Documentation

Skills CLI Complete - Full phase summary
CLI Usage Guide - Comprehensive CLI documentation (660 lines)
Quick Reference - Command quick reference

Skills Commands

import - Import skills from SKILL.md format
export - Export skills to SKILL.md format
validate - Validate skills against specifications
list - List all discovered skills
info - Show detailed skill information

Skills CLI Compatibility

Agent Skills: 100% validation support
Claude Code: 95% validation support
Bidirectional: Import/export both formats

📦 Phase 2.4: Build System & Package Manager (100% Complete)

Build System Documentation

Build System Complete - Full phase summary
Build System Guide - Comprehensive guide (700+ lines)
Quick Reference - Command quick reference

Package Management Commands

pcl init - Initialize new PCL projects
pcl build - Build projects to multiple formats
pcl install - Install and manage dependencies
Lock Files - Reproducible builds with pcl-lock.json
Dependency Resolution - Automatic transitive dependencies

Build Output Targets

prompt - Text prompts (.prompt.txt) per persona
json - JSON representation (.json)
yaml - YAML representation (.yaml)
typescript - TypeScript types (.ts)
markdown - Documentation (.md)

Build System Features

NPM-compatible package format
Semantic versioning support
Version ranges (^, ~, >=, etc.)
Circular dependency detection
Version conflict detection

Ecosystem Specifications

Agent Skills Spec - Official Agent Skills specification
Claude Code Skills - Official Claude Code documentation
PCL Skills Format - PCL native skill format

Skills Usage

Creating Skills - How to write skills
Using Skills - How to use skills in personas
Skill Loader API - TypeScript API reference
Example Skills - Production-ready examples

Example Skills

Python Expert - Python programming skill (270 lines)
More skills coming in standard library

Compatibility

Agent Skills: 100% compatible (all required + optional fields)
Claude Code: 95% compatible (100% core features)
Bidirectional: Import/export both formats
Progressive Disclosure: 3-tier loading pattern supported

🏛️ Governance & Compliance

Security & Standards

Security Model - ISO 27001/42001 security architecture
Governance Framework - ISO 38500 governance
Security Policy - Security practices and reporting

Standards Compliance

ISO/IEC 27001 - Information Security Management
ISO/IEC 42001 - AI Management System
OWASP LLM Top 10 - LLM security best practices
EU AI Act - High-risk AI regulation
NIST SP 800-207 - Zero Trust Architecture

Compliance Documents

Standards Alignment - How PCL meets standards
Risk Classification - AI risk levels
Audit Logging - Compliance logging

📖 Tutorials & Guides

Beginner

Getting Started - Your first PCL program
Basic Personas - Creating simple personas
Type System Basics - Understanding types

Intermediate

Team Composition - Multi-agent teams
Workflow Orchestration - Complex workflows
Registry Usage - Using the registry system
Skills Integration - Using skills from ecosystem

Advanced

Custom Providers - Building LLM providers
Plugin System - Extending PCL
Performance Tuning - Optimization techniques
Security Hardening - Production security

🔧 API Reference

Core APIs

Parser API - parse(), parseExpression(), etc.
Semantic API - analyze(), type checking
Runtime API - createRuntime(), execution
Registry API - RegistryManager, backends

LSP APIs

LSP Server API - Language server API
Document Manager - Document lifecycle
Providers - Completion, hover, etc.

Skills APIs

Skill Loader - Load and convert skills
Skill Resolver - Resolve skill references
Skill Compiler - Compile skills

Code Generation

Code Generator - Generate code
JSON Export - Export to JSON
YAML Export - Export to YAML
Markdown Export - Documentation generation

📋 Examples

Basic Examples

Hello World - Simplest persona
Simple Persona - Basic structure
Type Examples - Type system features

Advanced Examples

Multi-Agent Team - Team composition
Complex Workflow - Orchestration
Full Application - Complete application

Skill Examples

Python Expert - Programming skill
Code Review - Review skill
Data Analysis - Analysis skill

Test Examples

Parser Tests - Parser test cases
Semantic Tests - Type checker tests
Runtime Tests - Execution tests
Skills Tests - Skill loader tests

🛣️ Roadmap & Planning

Project Roadmap

ROADMAP.md - Complete project roadmap
Current Status - What's done

Phase Completion Documents

Phase 0 Complete - Foundation
Phase 1 Complete - Core language
Phase 2.1 Complete - LSP
Phase 2.2 Complete - Skills
Phase 2.3 Complete - Skills CLI
Phase 2.4 Complete - Build System
Phase 2 Validation - Phase 2 validation
Phase 2 Complete - Phase 2 summary

Current Phases (In Progress)

Phase 2.5-2.7 Plan - IDE Extensions, Skills Library, Registry
Phase 2.5-2.7 Progress - Current progress

Session Summaries

Session 2026-01-18 Final - Latest session summary
Session Summary Detailed - Detailed progress

Future Plans

Phase 3 Plan - Advanced features

🧪 Testing & Quality

Test Suites

Test Overview - Testing strategy
Unit Tests - Component tests
Integration Tests - End-to-end tests
Benchmarks - Performance benchmarks

Quality Assurance

Code Style Guide - Coding standards
Review Process - PR guidelines
Security Testing - Security validation

🤝 Contributing

Getting Involved

Contributing Guide - How to contribute
Code of Conduct - Community guidelines
Development Setup - Local development

Community

Discussions - Ask questions
Issues - Report bugs
Pull Requests - Contribute code

📜 Legal & Licensing

Licenses

LICENSE - Apache 2.0 license
NOTICE - Third-party notices
Copyright - Copyright information

Policies

Security Policy - Vulnerability reporting
Privacy Policy - Data handling
Terms of Use - Usage terms

🔍 Quick Reference

Quick Start Guides

Quickstart Guide - Get started in 5 minutes
Build System Quick Ref - Build commands reference
Skills CLI Quick Ref - Skills commands reference

Common Tasks

Task	Documentation
Install PCL	README.md
Quick Start	Quickstart Guide
Create first persona	Getting Started
Initialize PCL project	Build System Guide
Build PCL project	Build Quick Ref
Install dependencies	Build System Guide
Use VSCode extension	Extension README
Import Agent Skills	Agent Skills Guide
Import Claude Code skills	Claude Code Guide
Manage skills	Skills CLI Quick Ref
Set up registry	Registry Guide
Run tests	Testing Guide
Deploy to production	Deployment Guide

API Quick Links

API	Link
`parse()`	Parser API
`analyze()`	Semantic API
`createRuntime()`	Runtime API
`RegistryManager`	Registry API
`parseSkillMd()`	Skill Loader

Specification Quick Links

Spec	Link
Language Grammar	PCL_GRAMMAR.md
Type System	PCL_TYPE_SYSTEM.md
Security Model	PCL_SECURITY_MODEL.md
Agent Skills	agentskills.io/specification
Claude Code Skills	code.claude.com/docs

📊 Documentation Statistics

Category	Documents	Lines
Core Specs	5	~10,000
API Reference	15	~5,000
Tutorials	10	~3,000
Examples	25+	~2,000
Phase Completions	8	~5,000
Skills Documentation	3	~5,500
Governance	6	~4,000
Total	70+	~35,000

🆕 Latest Updates (2026-01-18)

Phase 2.1: LSP Implementation ✅

Complete Language Server Protocol with 8 features
VSCode extension with syntax highlighting
Real-time diagnostics, completion, hover, navigation
Full documentation

Phase 2.2: Skills Ecosystem ✅

100% compatible with Agent Skills specification
95% compatible with Claude Code SKILL.md format
Bidirectional conversion (PCL ↔ SKILL.md)
Full documentation
Claude Code guide
Agent Skills guide

📞 Support

Getting Help

Documentation: Start with this index
Examples: Check examples/
Discussions: GitHub Discussions
Issues: GitHub Issues

Reporting Issues

Bugs: Use bug report template
Features: Use feature request template
Security: Email security@pcl.dev (see SECURITY.md)

Last Updated: 2026-01-18 Documentation Version: 1.0.0 PCL Version: 1.0.0-alpha