A standardized .ai/ workspace structure for AI assistants — with an extension-only architecture for Claude Code, OpenClaw, Pi, Cursor, and Copilot.

The dot-ai convention provides a universal workspace structure that helps AI assistants understand your project context, manage tasks, route between projects, and maintain consistency across sessions. v7 replaces the provider system with a unified extension-only architecture where everything — identity, memory, skills, routing, tools — is an extension.

• 🏗️ Workspace Structure — Standardized .ai/ directory with boot sequence and project routing
• 🧩 Extension-Only Architecture — Everything is an extension: identity, memory, skills, routing, tools
• 🎯 Section-Based Context — Extensions return Section objects assembled by priority with token-budget trimming
• 📊 Token Budget — formatSections() auto-trims sections to fit context window with BudgetWarning diagnostics
• 🔧 Extension-Registered Tools — Tools defined in extensions, exposed as native agent capabilities
• 🔍 Deterministic Labels — Regex-based label extraction from vocabulary (no LLM in pipeline)
• 🚀 DotAiRuntime — Single class encapsulating boot, processPrompt, fireToolCall, fire, shutdown
• 🔄 5 Emission Patterns — fire, fireCollectSections, fireFirstResult, fireChainTransform, fireUntilBlocked
• 📡 Boot Caching — Extensions discovered once per session, vocabulary built at boot

# Install the plugin
claude plugin add dot-ai

For programmatic use or custom adapters:

npm install @dot-ai/core @dot-ai/adapter-claude

Available packages:

openclaw plugins install dot-ai
openclaw gateway restart

Use the adapter-sync package to generate agent-specific configuration:

npx @dot-ai/adapter-sync

This generates:

• Windsurf: .windsurf/rules/dot-ai.md
• Cursor: .cursor/rules/dot-ai.md
• Codex: Injects into root AGENTS.md
• Continue.dev: Manual reference in .continuerc.json

mkdir -p my-project/.ai/memory/tasks
cd my-project/.ai

Create .ai/AGENTS.md:

# AGENTS.md

This workspace follows the dot-ai convention.

## Project

{Brief description of your project}

## Conventions

- Read `.ai/skills/dot-ai/BOOTSTRAP.md` for workspace rules
- Use `dot-ai-tasks` for task management (not built-in todos)
- Follow model routing guidelines

The plugin automatically detects any workspace with .ai/AGENTS.md and:

• ✅ Loads workspace context at session start
• ✅ Discovers and activates extensions from .ai/extensions/ and installed packages
• ✅ Enforces task management conventions
• ✅ Optimizes model selection for sub-agents
• ✅ Provides access to all skills and capabilities

No local installation needed — the plugin provides skills globally!

Extensions are the only mechanism for contributing content in v7. Place TypeScript files in .ai/extensions/ or install extension packages — they are loaded automatically at boot.

// .ai/extensions/security-gate.ts
import type { ExtensionAPI } from '@dot-ai/core';

export default function(api: ExtensionAPI) {
  // Gate tool calls
  api.on('tool_call', async (event) => {
    if (event.tool === 'Write' && event.input.file_path?.toString().endsWith('.env')) {
      return { decision: 'block', reason: 'Cannot write to .env files' };
    }
  });

  // Enrich context with sections
  api.on('context_enrich', async (event) => {
    return {
      sections: [{
        title: 'Security Rules',
        content: '> Always write tests for new features.',
        priority: 70,
        source: 'security-gate',
      }],
    };
  });

  // Register skills, identities, labels
  api.registerSkill({ name: 'security', description: 'Security rules', labels: ['security'] });
  api.contributeLabels(['security', 'auth', 'secrets']);
}

Extensions receive an ExtensionAPI object with:

Not all adapters support every event. The matrix below shows what each adapter can fire:

See docs/extensions.md for the full extension authoring guide.

my-project/
├── .ai/                        # Root workspace context
│   ├── AGENTS.md               # Required — AI operating rules
│   ├── SOUL.md                 # Optional — Workspace personality
│   ├── USER.md                 # Optional — User preferences
│   ├── IDENTITY.md             # Optional — Project identity
│   ├── TOOLS.md                # Optional — Tool configuration
│   │
│   ├── extensions/             # User-authored extensions (v7)
│   │   └── *.ts                # Loaded automatically at boot
│   │
│   ├── memory/                 # Session memory and tasks
│   │   ├── YYYY-MM-DD.md       # Daily session notes
│   │   ├── tasks/              # Task details (on-demand)
│   │   │   └── {slug}.md
│   │   └── research/           # Research notes
│   │
│   ├── data/                   # Structured data ONLY (no drafts!)
│   │   ├── exports/            # Generated exports (CSV, JSON)
│   │   └── imports/            # External data imports
│   │
│   └── skills/
│       └── dot-ai/             # Symlink to plugin skills (auto-created)
│           ├── BOOTSTRAP.md    # Lightweight startup context
│           ├── SKILL.md        # Full documentation
│           ├── CONVENTIONS.md  # Shared conventions
│           └── templates/      # Reusable templates
│
└── projects/                   # Sub-projects (optional)
    └── {project-name}/
        └── .ai/                # Per-project AI context
            ├── AGENT.md        # Project-specific docs
            └── memory/
                └── tasks/

• Root .ai/ — Workspace-wide context
• Project .ai/ — Project-specific context
• Extensions — .ai/extensions/ and installed packages loaded at boot
• Data Separation — .ai/data/ = structured only, no research/drafts
• Memory Organization — Daily notes, tasks, research separated

Always use dot-ai-tasks instead of built-in todos.

Tasks are managed through the task extension. The extension can be backed by:

• File-based (@dot-ai/ext-file-tasks) — JSON files in .ai/memory/tasks/
• Custom — Any extension implementing the task pattern

Configure in .ai/settings.json:

{
  "packages": [
    "@dot-ai/ext-file-tasks"
  ]
}

Tasks support standard fields: id, text, status, priority, project, tags.

The plugin automatically injects model routing rules:

Task Type                  →  Model to Use
─────────────────────────────────────────────────
OCR, extraction, formatting  →  Haiku (cheap)
Development, refactoring     →  Sonnet (standard)
Architecture, planning       →  Opus (strategic only)

Anti-patterns:

• ❌ Never spawn sub-agent without specifying model
• ❌ Never use Opus for execution tasks
• ❌ Never do multiple web_fetch in Opus

The plugin monitors context usage and suggests delegation:

Context Usage  →  Action
───────────────────────────────────────
< 50%          →  Normal operation
50-70%         →  Delegate reads to sub-agents
> 70%          →  Switch to Sonnet if on Opus
> 85%          →  Stop reading, work from memory

Run workspace diagnostics:

"doctor" or "health check"

Output:

🏥 dot-ai Health Check

Overall Health: 85/100 (Good)

✅ Passed (5):
  - Structure validation
  - Required files
  - Extension loading
  - Cache fresh (<7 days)

⚠️ Warnings (2):
  - 3 orphan tasks without backlog refs
  - 1 extension failed to load (syntax error)

💊 Suggested Fixes:
  1. Run backlog-sync to add orphan tasks
  2. Check .ai/extensions/ for syntax errors

Agent (Claude Code / OpenClaw / Pi / Cursor / Copilot)
  └── Adapter (hooks into native events)
        └── DotAiRuntime (@dot-ai/core)
              ├── boot()           → discover extensions, register resources, build vocabulary
              ├── processPrompt()  → label_extract, context_enrich, route → { sections, labels, routing }
              ├── fireToolCall()   → extension-based tool gating
              ├── fire('agent_end', { response })  → notify extensions
              ├── shutdown()       → session_end + flush
              └── diagnostics      → extension status

  Extensions (everything is an extension):
  ├── ext-file-identity     → registerIdentity(), context_enrich
  ├── ext-file-memory       → context_enrich, agent_end
  ├── ext-file-skills       → registerSkill(), context_enrich
  ├── ext-rules-routing     → route event handler
  ├── ext-file-tasks        → registerTool(), context_enrich
  ├── ext-file-tools        → registerTool(), context_enrich
  ├── ext-file-prompts      → context_enrich
  ├── ext-sqlite-memory     → context_enrich, agent_end
  └── .ai/extensions/*.ts   → user-authored extensions

See ARCHITECTURE.md for the full technical reference.

All large skills (>100 lines) use INDEX/SKILL separation:

• INDEX.md (~30-40 lines) — Quick reference at startup

  • Purpose and triggers
  • Quick commands
  • Key concepts
  • Use cases
  • Pointer to SKILL.md

• SKILL.md (full docs) — Loaded on-demand

  • Detailed procedures
  • Examples and edge cases
  • Templates and validation rules
  • Integration points

Benefits:

• ✅ Fast startup (agent sees overview)
• ✅ Complete awareness (knows what exists)
• ✅ Progressive loading (details when needed)

• CONVENTIONS.md — Single source of truth for:

  • Marker patterns
  • Frontmatter schema
  • Output formats
  • Validation workflows
  • Directory structure

• templates/ — Reusable templates:

  • BACKLOG.template.md
  • AGENT.template.md
  • SKILL.template.md
  • task-details.template.md
  • validation-output.template.md

The central configuration file at .ai/settings.json:

{
  "packages": [
    "@dot-ai/ext-file-identity",
    "@dot-ai/ext-file-memory",
    "@dot-ai/ext-file-skills",
    "@dot-ai/ext-rules-routing",
    "@dot-ai/ext-file-tasks",
    "@dot-ai/ext-file-tools"
  ],
  "extensions": [
    ".ai/extensions/custom.ts"
  ],
  "debug": {
    "logPath": ".ai/debug.log"
  }
}

User-level defaults can be set in ~/.ai/settings.json. These are merged with project-level settings (arrays deduplicated, project scalars win):

{
  "packages": [
    "@dot-ai/ext-file-identity",
    "@dot-ai/ext-file-memory"
  ]
}

Packages listed in settings.json are automatically installed into .ai/packages/ at boot if not already present. No manual npm install needed.

Each adapter resolves the workspace root (the directory containing .ai/) and passes it to DotAiRuntime. The resolution priority varies by adapter:

OpenClaw adapter:

Claude Code adapter: Uses the hook's cwd (always the project directory).

Pi adapter: Uses the configured workspaceRoot option.

In openclaw.json, configure the workspace path for gateway/Discord/TUI environments under plugins.entries.dot-ai.config:

{
  "plugins": {
    "entries": {
      "dot-ai": {
        "enabled": true,
        "config": {
          "workspace": "/Users/you/dev/my-project"
        }
      }
    }
  }
}

Uses .claude-plugin/plugin.json for metadata and skill registration.

• ARCHITECTURE.md — Full v7 architecture (runtime, extensions, events, formatting)
• docs/extensions.md — Extension authoring guide (events, custom tools, best practices)
• BOOTSTRAP.md — Lightweight startup context (what agent sees at boot)
• SKILL.md — Full dot-ai convention documentation
• CONVENTIONS.md — Shared conventions across all skills

1. Create skill directory: skills/my-skill/
2. Create INDEX.md (~30 lines) with overview
3. Create SKILL.md with full documentation
4. Add skill to manifests:
   • openclaw.plugin.json → skills array
   • .claude-plugin/plugin.json → skills array
5. Update plugin injection in index.ts if needed

1. Create a .ts file in .ai/extensions/ or a new ext-* package
2. Export a default function that receives ExtensionAPI
3. Register resources (registerSkill, registerIdentity, contributeLabels)
4. Subscribe to events (context_enrich, tool_call, agent_end, etc.)
5. Extensions are loaded automatically at boot — no registration needed

Releases are CI-only — never run the release script locally.

• Trigger: Manual workflow_dispatch on GitHub Actions (.github/workflows/release.yml)
• Versioning: All packages use fixed versioning (same version). Current version is resolved from git tags, not package.json.
• Bump detection: Automatic via conventional commits (feat: → minor, fix: → patch)
• What happens:
  1. Bumps all packages/*/package.json
  2. Syncs plugin manifests (openclaw.plugin.json, .claude-plugin/plugin.json, etc.)
  3. Generates CHANGELOG.md, creates git commit & tag
  4. Publishes all packages to npm

• Follow INDEX/SKILL pattern for skills >100 lines
• Reference CONVENTIONS.md for shared patterns
• Use templates from templates/ directory
• Include frontmatter with name, description, triggers
• Add cross-references to related skills
• Write clear examples and use cases

# OpenClaw
openclaw plugins list
openclaw gateway restart

# Claude Code
claude plugin list
claude plugin enable dot-ai

Check that .ai/AGENTS.md exists:

ls -la .ai/

If missing, create it or run:

"init project {name}"

Check the diagnostics output:

"doctor" or "health check"

Common issues:

• Syntax error in .ts file
• Missing default export
• Listening to events not supported by current adapter

Run diagnostics and follow suggested fixes from the output.

The plugin provides skills globally. If skills aren't working:

1. Verify plugin is enabled
2. Restart agent/gateway
3. Check workspace has .ai/AGENTS.md

Startup injection:

• Before optimization: 1582 lines
• After optimization: 620 lines
• Reduction: 61% (962 lines saved)

Strategy:

• INDEX.md files provide overview (520 lines)
• SKILL.md files loaded on-demand (1600+ lines)
• Agent maintains 100% awareness with 61% fewer tokens

Impact:

• ✅ Faster startup across all adapters
• ✅ More context budget for actual work
• ✅ Same functionality, better performance

MIT License — See LICENSE for details.

• Repository: https://github.com/jogelin/dot-ai
• Issues: https://github.com/jogelin/dot-ai/issues
• OpenClaw: https://github.com/openclaw/openclaw
• Claude Code: https://claude.ai/claude-code

dot-ai provides a universal workspace convention for AI assistants:

• ✅ Standardized .ai/ structure with multi-project support
• ✅ Extension-only architecture — everything (identity, memory, skills, routing, tools) is an extension
• ✅ Section-based context enrichment via context_enrich event
• ✅ DotAiRuntime with boot, processPrompt, fireToolCall, fire, shutdown
• ✅ 5 emission patterns (fire, fireCollectSections, fireFirstResult, fireChainTransform, fireUntilBlocked)
• ✅ Token budget with section-aware trimming (formatSections, trimSections)
• ✅ Deterministic label-based matching (no LLM in pipeline)
• ✅ Boot caching for fast per-prompt enrichment
• ✅ Works with Claude Code, OpenClaw, Pi, Cursor, Copilot

Get started: Create .ai/AGENTS.md in your project root and let the plugin handle the rest!

Made with ❤️ by the dot-ai community

Last updated: 2026-03-07