Skip to content

Commit 8b47870

Browse files
MichaelYochpazMichaelYochpaz
committed
Initial commit
0 parents  commit 8b47870

52 files changed

Lines changed: 4596 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.ai-workspace/README.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# AI Workspace Infrastructure
2+
3+
This directory contains the infrastructure for the AI Workspace Template.
4+
5+
**Full documentation:** [Configuration Reference](https://michaelyochpaz.github.io/ai-workspace-template/configuration/)
6+
7+
## Directory Structure
8+
9+
```
10+
.ai-workspace/
11+
├── docs/ # Documentation source (Zensical site)
12+
├── lib/ # Python library (config models)
13+
├── scripts/ # Automation scripts
14+
├── templates/ # Jinja2 templates
15+
└── zensical.toml # Documentation site config
16+
```
17+
18+
## Key Scripts
19+
20+
| Script | Purpose |
21+
|--------|---------|
22+
| `setup.py` | One-time workspace setup (submodules, hooks, alignment) |
23+
| `align-workspace.py` | Pre-commit: regenerates AGENTS.md, manages feature dirs |
24+
| `session-start.py` | Session start: reports repo status, discovers tools |
25+
| `transpile-skills.py` | Validates and distributes skills |
26+
| `transpile-commands.py` | Validates and distributes commands |
27+
| `mktmpdir.py` | Creates unique task directories under `.tmp/` |
28+
29+
## AGENTS.md Generation
30+
31+
`AGENTS.md` is auto-generated from `templates/AGENTS.md.j2`. Don't edit directly.
32+
33+
- **Workspace instructions:** Edit `templates/AGENTS.md.j2`
34+
- **Project-specific instructions:** Edit `AGENTS.project.md` at repo root
35+
36+
Regenerate manually:
37+
```bash
38+
uv run .ai-workspace/scripts/align-workspace.py
39+
```
40+
41+
## Configuration
42+
43+
The workspace is configured via `ai-workspace.toml` at the repository root. Key sections:
44+
45+
| Section | Purpose |
46+
|---------|---------|
47+
| `[repositories]` | Repository status and sync settings |
48+
| `[features]` | Enable/disable skills, commands, agent-docs |
49+
| `[tools]` | Tool discovery settings |
50+
| `[distribution]` | Where to distribute skills/commands |
51+
52+
See [Configuration](https://michaelyochpaz.github.io/ai-workspace-template/configuration/) for the full reference.
53+
54+
## Documentation Site
55+
56+
Built with [Zensical](https://zensical.org/). Config in `zensical.toml`.
57+
58+
```bash
59+
# Preview locally
60+
zensical serve --config-file .ai-workspace/zensical.toml
61+
62+
# Build static site
63+
zensical build --config-file .ai-workspace/zensical.toml
64+
```

‎.ai-workspace/docs/agents-md.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# AGENTS.md Generation
2+
3+
`AGENTS.md` is the primary file AI agents read when starting a session. It contains workspace instructions, operational guidelines, documentation listings, and your project-specific content. This workspace auto-generates it from a Jinja2 template so that it stays in sync with your configuration and agent docs.
4+
5+
## Why auto-generate?
6+
7+
A manually maintained `AGENTS.md` falls out of sync as you add agent docs, enable/disable features, or change workspace structure. Auto-generation ensures the file always reflects the current state:
8+
9+
- **Agent docs listing** - Automatically updated when you add, remove, or edit docs in `agent-docs/`
10+
- **Feature sections** - Skills and commands sections appear only when those features are enabled and have content
11+
- **Consistent structure** - Workspace-level instructions (submodule workflow, pre-commit, temporary files) are maintained in the template, separate from your project-specific content
12+
13+
## Writing your instructions
14+
15+
Edit `AGENTS.project.md` at the repo root. This is where you write your own instructions and context for AI agents - the same kind of content you'd normally put in a regular `AGENTS.md`:
16+
17+
```markdown
18+
## Project Overview
19+
Brief description of what this project does.
20+
21+
## Key Concepts
22+
- **Term 1** - Definition
23+
- **Term 2** - Definition
24+
25+
## Repository Structure
26+
- `repositories/backend/` - Go API server
27+
- `repositories/frontend/` - React web app
28+
```
29+
30+
This content is injected into the generated `AGENTS.md` under a "Project-Specific Context" heading. The file ships with `<placeholder>` tags - remove them when adding your content (the placeholder content is ignored during generation).
31+
32+
## Instruction priority with submodule repositories
33+
34+
Each repository under `repositories/` may have its own `AGENTS.md` (or `CLAUDE.md`) with repo-specific instructions. The generated workspace `AGENTS.md` instructs agents to:
35+
36+
1. **Read and follow submodule instructions** - Agents read the submodule's `AGENTS.md` and `README.md` before making changes, and follow repo-specific conventions, commands, and boundaries
37+
2. **Workspace takes priority on conflicts** - If a submodule instruction conflicts with the workspace-level `AGENTS.md`, the workspace instruction wins. This covers workspace-wide concerns like submodule workflow, package management, pre-commit, and documentation systems
38+
39+
This means submodule `AGENTS.md` files don't need to repeat workspace-level instructions, and teams can maintain repo-specific conventions without worrying about conflicts.
40+
41+
## Regeneration
42+
43+
`AGENTS.md` is regenerated automatically on every pre-commit run. You can also regenerate it manually:
44+
45+
```bash
46+
# Via pre-commit (also runs all other hooks)
47+
uv run pre-commit run --all-files
48+
49+
# Directly (only runs workspace alignment)
50+
uv run .ai-workspace/scripts/align-workspace.py
51+
```
52+
53+
!!! warning "Do not edit AGENTS.md directly"
54+
55+
Any manual edits to `AGENTS.md` will be overwritten on the next pre-commit run.
56+
57+
Edit `AGENTS.project.md` for your instructions, or [modify the template](#modifying-the-template-advanced) to change workspace-level structure.
58+
59+
## Modifying the template (advanced)
60+
61+
!!! warning
62+
63+
The template controls core workspace functionality - agent docs integration, feature-gated sections, submodule workflow instructions, and more. Incorrect modifications can break these features.
64+
65+
Only modify the template if you understand how the workspace uses it.
66+
67+
The [Jinja2](https://jinja.palletsprojects.com/en/stable/templates/) template at `.ai-workspace/templates/AGENTS.md.j2` defines the structure and workspace-level instructions of the generated `AGENTS.md`. Most users won't need to touch this file - `AGENTS.project.md` covers project-specific customization. But if you need to change the workspace-level instructions themselves (reword guidelines, add new sections, remove parts that don't apply), you can edit the template directly.
68+
69+
### Available template variables
70+
71+
The template receives these variables during rendering:
72+
73+
`features.agent_docs.enabled`
74+
: **Type:** bool - Whether the agent docs feature is enabled
75+
76+
`features.agent_docs.docs`
77+
: **Type:** list - Agent doc entries (each has `display_name`, `description`, `when_to_read`, `doc_path`)
78+
79+
`features.skills.enabled`
80+
: **Type:** bool - Whether the skills feature is enabled
81+
82+
`features.skills.count`
83+
: **Type:** int - Number of validated skills
84+
85+
`features.commands.enabled`
86+
: **Type:** bool - Whether the commands feature is enabled
87+
88+
`features.commands.count`
89+
: **Type:** int - Number of validated commands
90+
91+
`project_content`
92+
: **Type:** str or None - Content of `AGENTS.project.md` (None if missing or placeholder)
93+

‎.ai-workspace/docs/configuration.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# Configuration
2+
3+
The workspace is configured via `ai-workspace.toml` at the repository root. Most settings have sensible defaults - distribution paths must be explicitly configured for your project.
4+
5+
## Full example
6+
7+
Here's a complete config file showing all settings.
8+
Distribution paths (`skills_paths`, `commands_paths`) default to empty and must be configured for your tools:
9+
10+
```toml
11+
[repositories]
12+
include_workspace_root = false
13+
14+
[features]
15+
skills = true
16+
commands = true
17+
agent_docs = true
18+
19+
[tools]
20+
show_unavailable = false
21+
22+
[distribution]
23+
skills_paths = [".opencode/skill"]
24+
commands_paths = [
25+
".claude/commands",
26+
".cursor/commands",
27+
".opencode/command",
28+
]
29+
30+
[distribution.commands_overrides]
31+
".cursor/commands" = "strip_frontmatter"
32+
```
33+
34+
---
35+
36+
## Repositories
37+
38+
Controls repository status reporting at session start. Section: `[repositories]`
39+
40+
`include_workspace_root`
41+
: **Type:** bool - **Default:** `false`
42+
43+
Include the workspace root repo in session status
44+
45+
The default branch for each submodule is auto-detected at session start. If detection fails (e.g., a submodule uses a non-standard default branch like `develop`), set the `branch` field in `.gitmodules` for that submodule.
46+
See [Repositories](repositories.md#default-branch-detection) for details.
47+
48+
---
49+
50+
## Session hooks
51+
52+
Session hooks are pre-configured in each tool's config directory - they're committed to the repo and work out of the box. No configuration needed.
53+
54+
The session-start script runs repository status reporting and tool discovery, then injects the results into the agent's context. See [Session Hooks](development/session-hooks.md) for supported tools and details.
55+
56+
---
57+
58+
## Features
59+
60+
Enable or disable workspace features. Section: `[features]`
61+
62+
`skills`
63+
: **Type:** bool - **Default:** `true`
64+
65+
Enable the skills system (`skills/` directory)
66+
67+
`commands`
68+
: **Type:** bool - **Default:** `true`
69+
70+
Enable the commands system (`commands/` directory)
71+
72+
`agent_docs`
73+
: **Type:** bool - **Default:** `true`
74+
75+
Enable the agent-docs system (`agent-docs/` directory)
76+
77+
**What happens when you change these:**
78+
79+
- **Enabling** a feature creates its directory with a README if it doesn't exist
80+
- **Disabling** a feature removes its directory **only if it's empty** (or contains just a README).
81+
If the directory has user content, pre-commit fails with instructions to manually remove the files first
82+
83+
!!! note
84+
85+
This prevents accidental data loss while letting you cleanly disable unused features.
86+
87+
---
88+
89+
## Tools
90+
91+
Controls the [Tool Discovery](features/tool-discovery.md) feature. Section: `[tools]`
92+
93+
`show_unavailable`
94+
: **Type:** bool - **Default:** `false`
95+
96+
Show all defined tools with availability status, or only available ones
97+
98+
**Behavior:**
99+
100+
- `false` (default) - Only tools found on the system PATH are shown to agents. Clean and focused.
101+
- `true` - All tools are shown with `available="true"` or `available="false"`. Useful when you want agents to know about tools they *could* use if installed.
102+
103+
Tools themselves are defined in `agent-tools.yaml` at the repo root, not in this config file. See [Tool Discovery](features/tool-discovery.md) for details on defining tools.
104+
105+
---
106+
107+
## Distribution
108+
109+
Controls where skills and commands are distributed for different AI tools. Section: `[distribution]`
110+
111+
Distribution paths default to empty - you must explicitly configure them for the tools you use.
112+
113+
`skills_paths`
114+
: **Type:** list[str] - **Default:** `[]`
115+
116+
Target directories for skills symlinks
117+
118+
`commands_paths`
119+
: **Type:** list[str] - **Default:** `[]`
120+
121+
Target directories for commands
122+
123+
`commands_overrides`
124+
: **Type:** dict[str, str] - **Default:** `{}`
125+
126+
Override distribution method for specific command paths. Keys are paths from `commands_paths`, values are distribution methods (`symlink` or `strip_frontmatter`). Overrides for paths not yet in `commands_paths` are kept for future use (a warning is printed during distribution).
127+
128+
### Distribution methods
129+
130+
Skills and commands in their source directories (`skills/`, `commands/`) are the source of truth. The transpile scripts distribute them to tool-specific directories:
131+
132+
| Method | How it works |
133+
|--------|-------------|
134+
| **Symlink** | Default for all paths. Creates a symlink pointing to the source file/directory. |
135+
| **Strip frontmatter** | Writes a copy with the YAML frontmatter removed. Use for tools that don't parse frontmatter. |
136+
137+
The `strip_frontmatter` method is needed for tools that send frontmatter to the LLM as part of the prompt instead of parsing it as metadata. For example, at the time of writing, [Cursor](https://cursor.com/docs/context/commands) doesn't support frontmatter metadata in commands.
138+
139+
### Configuring distribution
140+
141+
Add your tool's paths to the appropriate list. Use `commands_overrides` to set `strip_frontmatter` for tools that need it:
142+
143+
```toml
144+
[distribution]
145+
skills_paths = [
146+
".opencode/skill",
147+
]
148+
commands_paths = [
149+
".claude/commands",
150+
".cursor/commands",
151+
".opencode/command",
152+
]
153+
154+
[distribution.commands_overrides]
155+
".cursor/commands" = "strip_frontmatter"
156+
```
157+
158+
See [Commands](features/commands.md#distribution) for more details on how distribution works.
159+
160+
---
161+
162+
## How configuration is applied
163+
164+
Configuration is applied at two points:
165+
166+
1. **Pre-commit** (`align-workspace.py`) - Reads `ai-workspace.toml` and:
167+
- Manages feature directories (create/remove based on `[features]`)
168+
- Renders `AGENTS.md` from the Jinja2 template
169+
- Runs skill and command validators
170+
171+
2. **Session start** (`session-start.py`) - Reads `ai-workspace.toml` and:
172+
- Reports repository status based on `[repositories]` settings
173+
- Discovers tools based on `[tools]` settings
174+
175+
After changing `ai-workspace.toml`, run pre-commit to apply:
176+
177+
```bash
178+
uv run pre-commit run --all-files
179+
```
180+
181+
## AGENTS.md generation
182+
183+
`AGENTS.md` is auto-generated from a Jinja2 template and your project-specific content. See [AGENTS.md Generation](agents-md.md) for how the template system works, available template variables, and customization options.

0 commit comments

Comments
 (0)