Skip to content

AI Workspace Template

A meta-repository template that aggregates related repositories using git submodules, creating a unified workspace for AI agents to operate across your project ecosystem.

Features

  • Repositories

    Aggregate repos as submodules with automatic git status reporting to agents

    Learn more

  • Agent Docs

    Modular docs that agents selectively load based on task relevance

    Learn more

  • AGENTS.md Generation

    Auto-generate agent instructions from templates and config on every commit

    Learn more

  • Tool Discovery

    Detect installed CLI tools and inject usage instructions into agent context

    Learn more

  • Skills

    Distribute skill directories to tool-specific paths via symlinks

    Learn more

  • Commands

    Distribute command files across tools, converting formats where needed

    Learn more

  • Temporary Files

    Git-ignored workspace for agent artifacts, organized by task

    Learn more

How it works

Session hooks

Some AI tools support hooks - scripts that run automatically at specific lifecycle points (e.g., session start, pre-prompt). This workspace uses a session-start hook to inject context into the agent before it begins work.

For tools with hook support (Claude Code, OpenCode, Cursor, Gemini CLI), the session-start script runs automatically when an AI session begins:

graph LR
  A[AI Session Starts] --> B[Session Hook Fires]
  B --> C[Fetch Repo Status]
  B --> D[Discover CLI Tools]
  C --> E[Inject Context into Agent]
  D --> E

The agent immediately knows which repos exist, what branch each is on, whether there are uncommitted changes, and which CLI tools are available.

Pre-commit validation

Separately, on every commit, pre-commit hooks keep the workspace aligned:

  • Regenerate AGENTS.md from templates and config
  • Validate skill and command definitions
  • Sync workspace structure with config

These are two independent flows - session hooks handle runtime context, pre-commit handles workspace integrity.

Other AI tools

Tools without hook support still work with skills, commands, and agent docs - they just won’t get automatic session-start context injection. See Session Hooks for which tools are supported and how to add more.

Project structure

workspace/
├── .ai-workspace/         # Infrastructure (scripts, templates, config)
├── agent-docs/            # Documentation modules for AI agents
├── commands/              # Cross-tool AI commands (/command-name)
├── skills/                # Agent skills (SKILL.md files)
├── repositories/          # Git submodules (your projects)
├── .tmp/                  # Git-ignored directory for agent work artifacts
├── agent-tools.yaml       # CLI tool definitions for discovery
├── ai-workspace.toml      # Workspace configuration
├── AGENTS.md              # Auto-generated (do not edit directly)
└── AGENTS.project.md      # Your agent instructions (merged into AGENTS.md)

Design principles

  • Model agnostic - Works with any AI model or tool. No vendor lock-in.
  • Context-rich - Agents get repo status, tool availability, and docs for autonomous work.
  • Fully automated - Pre-commit validates, session hooks inject context. No manual steps.
  • Efficient - Modular docs keep token usage low. Agents load only what’s relevant.
  • Cross-tool - One source of truth, distributed to multiple tool directories.