Skip to content

AGENTS.md

Latest commit

 

History

History
146 lines (108 loc) · 3.98 KB

AGENTS.md

File metadata and controls

146 lines (108 loc) · 3.98 KB

AGENTS.md - Plugin Documentation Guidelines

This file provides guidelines for AI agents working with the Cortex CLI plugin documentation.

Documentation Structure

plugins-docs/
├── README.md                    # Main index with links
├── AGENTS.md                    # This file
├── getting-started/
│   ├── overview.md              # Plugin system overview
│   ├── quick-start.md           # Create first plugin
│   └── plugin-structure.md      # Directory layout
├── reference/
│   ├── manifest.md              # plugin.toml reference
│   ├── capabilities.md          # Capability types
│   ├── permissions.md           # Permission types
│   ├── commands.md              # Custom commands
│   ├── hooks.md                 # Hook types
│   ├── events.md                # Event types
│   ├── api.md                   # Plugin API
│   ├── configuration.md         # System config
│   └── cli-commands.md          # CLI usage
├── guides/
│   ├── development.md           # Building plugins
│   ├── best-practices.md        # Security, performance
│   └── troubleshooting.md       # Common issues
└── examples/
    └── README.md                # Example plugins

Key Concepts

Plugin System

  • Plugins are WASM-based for security and portability
  • Run in isolated sandboxes
  • Must declare capabilities and permissions
  • Can add commands, hooks, and event handlers

Core Files

  • plugin.toml - Plugin manifest (required)
  • plugin.wasm - Compiled WASM module

Plugin Locations

  1. ~/.cortex/plugins/ - Global plugins
  2. ~/.config/cortex/plugins/ - Config directory
  3. ./.cortex/plugins/ - Project-local

Documentation Guidelines

When Adding Documentation

  1. Keep files focused - One topic per file
  2. Use consistent headers - H1 for title, H2 for sections
  3. Include examples - Code samples for all features
  4. Link related docs - Cross-reference other pages
  5. Update README.md - Add new pages to index

Code Examples

Always provide complete, working examples:

# Good: Complete manifest example
[plugin]
id = "example"
name = "Example"
version = "1.0.0"

capabilities = ["commands"]

[[commands]]
name = "example"
description = "Example command"

Tables

Use tables for reference material:

Field Type Required Description
id string ✅ Unique identifier
name string ✅ Display name

Common Tasks

Adding a New Hook Type

  1. Document in reference/hooks.md
  2. Add to hook types table
  3. Include input/output fields
  4. Provide example

Adding a New Permission

  1. Document in reference/permissions.md
  2. Add to permission types section
  3. Include TOML syntax example
  4. Note required capabilities

Adding a New Event

  1. Document in reference/events.md
  2. Add JSON example
  3. List event fields

Related Code

The plugin system implementation is in:

  • cortex-plugins/src/ - Plugin system crate
  • cortex-plugins/src/manifest.rs - Manifest parsing
  • cortex-plugins/src/hooks.rs - Hook types
  • cortex-plugins/src/events.rs - Event types
  • cortex-plugins/src/api.rs - Plugin API
  • cortex-cli/src/plugin_cmd.rs - CLI commands

Verification

When updating documentation:

  1. Verify code examples compile/work
  2. Check all links are valid
  3. Ensure consistency with implementation
  4. Test CLI commands mentioned

Style Guide

  • Use backticks for code, commands, and file names
  • Use bold for important terms on first use
  • Use bullet points for lists
  • Keep paragraphs short (3-5 sentences max)
  • Include "Next Steps" sections

Notes for AI Agents

  • The plugin documentation is separate from main AGENTS.md
  • Plugin source is in cortex-plugins/ crate
  • CLI plugin commands are in cortex-cli/src/plugin_cmd.rs
  • Always check implementation matches documentation
  • Update docs when plugin system changes