AI Workspace Template

A unified, multi-repo workspace for AI coding agents and developers.

Unified instructions, docs, skills, and commands — one source of truth across Claude Code, Cursor, OpenCode, and more.

📖 Documentation

The Problem

AI agents work great inside a single repo. But real projects span multiple repositories, and that's where things break down — agents can't see code in other repos, don't know what branch each one is on, and can't coordinate changes across boundaries. Your AI configuration ends up duplicated and out of sync across tools.

flowchart TB
    subgraph workspace[" AI Workspace "]
        config["AGENTS.md · Agent Docs · Skills · Commands"]
        repos["backend · frontend · infra"]
    end

    workspace -- "full context at session start" --> agent(["🤖 AI Agent"])

Loading

✨ Features

• 📂 Cross-repo visibility — All your repositories live as git submodules in one workspace. Agents see everything.

• 📋 Modular agent docs — Write focused documentation in agent-docs/ that agents selectively read based on task relevance. Dozens of docs, minimal token usage.

• 🔍 Tool discovery — Define CLI tools your team uses (gh, glab, jq, etc.). The workspace detects what's installed and tells agents how to use them — automatically, at session start.

• ⚡ Skills & commands — Define once in skills/ and commands/, distribute automatically to every AI tool's expected directory. One source of truth.

• 🔄 Auto-generated AGENTS.md — Your agent instructions, doc listings, and workspace config are merged from templates on every commit. Always in sync, never stale.

• 📊 Repository status — At session start, agents are told each repo's branch, uncommitted changes, and how far behind the remote. No more "which branch am I on?" confusion.

• 🔁 Runs locally and in CI — Clone the AI workspace on a developer's laptop or in a CI pipeline — agents will get identical instructions, docs, and tools in a reproducible environment.

• 🗂️ Organized artifacts — A git-ignored .tmp/ directory with task-based subdirectories keeps agent-generated files out of your codebase.

🛠️ Supported Tools

Session hooks are pre-configured for Claude Code, Cursor, OpenCode, and Gemini CLI — they work out of the box with no setup needed.

Any AI tool that reads AGENTS.md works with this workspace. Skills and commands can be distributed to any tool by configuring target paths in ai-workspace.toml. See the Configuration docs for details.

🚀 Quick Start

1. Click "Use this template" on GitHub to create your workspace repository, or clone it directly if you're using another platform (GitLab, Bitbucket, etc.)

2. Set up:

uv sync
uv run .ai-workspace/scripts/setup.py

3. Add your repos:

git submodule add <url> repositories/<name>

See the Getting Started guide for detailed setup instructions.

📖 Documentation

Full docs at ai-workspace-template.michaelyo.dev

Guide	Description
Getting Started	Setup and first steps
Repositories	Submodule model and status reporting
Configuration	ai-workspace.toml reference
Agent Docs	Writing documentation for agents
Skills	Distributing agent skills across tools
Commands	Distributing commands across tools
Tool Discovery	CLI tool detection and context injection