Skip to content

Commit 3420748

Browse files
MichaelYochpazMichaelYochpaz
committed
Initial commit
0 parents  commit 3420748

50 files changed

Lines changed: 4238 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+
| `align-workspace.py` | Pre-commit: regenerates AGENTS.md, manages feature dirs |
23+
| `session-start.py` | Session start: reports repo status, discovers tools |
24+
| `transpile-skills.py` | Validates and distributes skills |
25+
| `transpile-commands.py` | Validates and distributes commands |
26+
| `mktmpdir.py` | Creates unique task directories under `.tmp/` |
27+
28+
## AGENTS.md Generation
29+
30+
`AGENTS.md` is auto-generated from `templates/AGENTS.md.j2`. Don't edit directly.
31+
32+
- **Workspace instructions:** Edit `templates/AGENTS.md.j2`
33+
- **Project-specific instructions:** Edit `AGENTS.project.md` at repo root
34+
35+
Regenerate manually:
36+
```bash
37+
uv run .ai-workspace/scripts/align-workspace.py
38+
```
39+
40+
## Configuration
41+
42+
The workspace is configured via `ai-workspace.toml` at the repository root. Key sections:
43+
44+
| Section | Purpose |
45+
|---------|---------|
46+
| `[workspace]` | General settings (name) |
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: 237 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
# Configuration
2+
3+
The workspace is configured via `ai-workspace.toml` at the repository root. All settings have sensible defaults -- you only need to change what's relevant to your project.
4+
5+
## Full example
6+
7+
Here's a complete config file with all defaults shown:
8+
9+
```toml
10+
[workspace]
11+
name = "AI Workspace"
12+
13+
[repositories]
14+
default_branch = "main"
15+
include_workspace_root = false
16+
[features]
17+
skills = true
18+
commands = true
19+
agent_docs = true
20+
21+
[tools]
22+
show_unavailable = false
23+
24+
[distribution]
25+
skills_paths = [".opencode/skill"]
26+
commands_paths = [
27+
".roo/commands",
28+
".claude/commands",
29+
".cursor/commands",
30+
".opencode/command",
31+
]
32+
33+
[distribution.commands_overrides]
34+
".cursor/commands" = "strip_frontmatter"
35+
```
36+
37+
---
38+
39+
## Workspace
40+
41+
General workspace metadata. Section: `[workspace]`
42+
43+
`name`
44+
: **Type:** string -- **Default:** `"AI Workspace"`
45+
46+
Display name shown in tool UIs
47+
48+
```toml
49+
[workspace]
50+
name = "My Project Workspace"
51+
```
52+
53+
---
54+
55+
## Repositories
56+
57+
Controls repository status reporting at session start. Section: `[repositories]`
58+
59+
`default_branch`
60+
: **Type:** string -- **Default:** `"main"`
61+
62+
Fallback branch when not specified in `.gitmodules`
63+
64+
`include_workspace_root`
65+
: **Type:** bool -- **Default:** `false`
66+
67+
Include the workspace root repo in session status
68+
69+
**Common customizations:**
70+
71+
- Set `default_branch = "develop"` if your team uses `develop` as the main branch
72+
- Set `include_workspace_root = true` to also report workspace root repo status to agents
73+
74+
---
75+
76+
## Session hooks
77+
78+
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.
79+
80+
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.
81+
82+
---
83+
84+
## Features
85+
86+
Enable or disable workspace features. Section: `[features]`
87+
88+
`skills`
89+
: **Type:** bool -- **Default:** `true`
90+
91+
Enable the skills system (`skills/` directory)
92+
93+
`commands`
94+
: **Type:** bool -- **Default:** `true`
95+
96+
Enable the commands system (`commands/` directory)
97+
98+
`agent_docs`
99+
: **Type:** bool -- **Default:** `true`
100+
101+
Enable the agent-docs system (`agent-docs/` directory)
102+
103+
**What happens when you change these:**
104+
105+
- **Enabling** a feature creates its directory with a README if it doesn't exist
106+
- **Disabling** a feature removes its directory **only if it's empty** (or contains just a README).
107+
If the directory has user content, pre-commit fails with instructions to manually remove the files first
108+
109+
!!! note
110+
111+
This prevents accidental data loss while letting you cleanly disable unused features.
112+
113+
---
114+
115+
## Tools
116+
117+
Controls the [Tool Discovery](features/tool-discovery.md) feature. Section: `[tools]`
118+
119+
`show_unavailable`
120+
: **Type:** bool -- **Default:** `false`
121+
122+
Show all defined tools with availability status, or only available ones
123+
124+
**Behavior:**
125+
126+
- `false` (default) -- Only tools found on the system PATH are shown to agents. Clean and focused.
127+
- `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.
128+
129+
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.
130+
131+
---
132+
133+
## Distribution
134+
135+
Controls where skills and commands are distributed for different AI tools. Section: `[distribution]`
136+
137+
`skills_paths`
138+
: **Type:** list[str] -- **Default:** `[".opencode/skill"]`
139+
140+
Target directories for skills symlinks
141+
142+
`commands_paths`
143+
: **Type:** list[str] -- **Default:** *(see below)*
144+
145+
Target directories for commands
146+
147+
`commands_overrides`
148+
: **Type:** dict[str, str] -- **Default:** *(see below)*
149+
150+
Override distribution method for specific command paths
151+
152+
**Default command paths:**
153+
154+
```toml
155+
commands_paths = [
156+
".roo/commands",
157+
".claude/commands",
158+
".cursor/commands",
159+
".opencode/command",
160+
]
161+
```
162+
163+
**Default overrides:**
164+
165+
```toml
166+
[distribution.commands_overrides]
167+
".cursor/commands" = "strip_frontmatter"
168+
```
169+
170+
### Distribution methods
171+
172+
Skills and commands in their source directories (`skills/`, `commands/`) are the source of truth. The transpile scripts distribute them to tool-specific directories:
173+
174+
| Method | When used | How it works |
175+
|--------|-----------|-------------|
176+
| **Symlink** | Default for all paths | Creates a symlink pointing to the source file/directory |
177+
| **Strip frontmatter** | `.cursor/*` paths (auto-detected) | Writes a copy with the YAML frontmatter removed |
178+
179+
Paths starting with `.cursor/` automatically use `strip_frontmatter` without needing an explicit override. For all other paths, the default is `symlink`.
180+
181+
### Overriding the distribution method
182+
183+
Use `commands_overrides` to change the method for specific paths:
184+
185+
```toml
186+
[distribution.commands_overrides]
187+
".cursor/commands" = "strip_frontmatter" # Auto-detected, but shown for clarity
188+
".my-tool/commands" = "strip_frontmatter" # Custom override for another tool
189+
```
190+
191+
Override keys must match a path in `commands_paths`. Valid methods: `symlink`, `strip_frontmatter`.
192+
193+
You can also override auto-detection -- for example, to force symlinks for a `.cursor/` path:
194+
195+
```toml
196+
[distribution.commands_overrides]
197+
".cursor/commands" = "symlink" # Override the auto-detection
198+
```
199+
200+
See [Commands](features/commands.md#distribution) for more details on how distribution works.
201+
202+
### Adding a new tool target
203+
204+
To distribute to an additional tool, add its path to the appropriate list:
205+
206+
```toml
207+
[distribution]
208+
skills_paths = [
209+
".opencode/skill",
210+
".my-tool/skills", # Add your tool's path
211+
]
212+
```
213+
214+
---
215+
216+
## How configuration is applied
217+
218+
Configuration is applied at two points:
219+
220+
1. **Pre-commit** (`align-workspace.py`) -- Reads `ai-workspace.toml` and:
221+
- Manages feature directories (create/remove based on `[features]`)
222+
- Renders `AGENTS.md` from the Jinja2 template
223+
- Runs skill and command validators
224+
225+
2. **Session start** (`session-start.py`) -- Reads `ai-workspace.toml` and:
226+
- Reports repository status based on `[repositories]` settings
227+
- Discovers tools based on `[tools]` settings
228+
229+
After changing `ai-workspace.toml`, run pre-commit to apply:
230+
231+
```bash
232+
uv run pre-commit run --all-files
233+
```
234+
235+
## AGENTS.md generation
236+
237+
`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)