Skip to content

Commit bcb4742

Browse files
MichaelYochpazMichaelYochpaz
committed
more stuff
1 parent c21e174 commit bcb4742

9 files changed

Lines changed: 381 additions & 37 deletions

File tree

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

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
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+
94+
!!! note "Template updates and upstream merges"
95+
96+
If you modify the template and later pull updates from the template upstream (see [Getting Started](getting-started.md#template-updates)), you may encounter merge conflicts in `AGENTS.md.j2`. Your customizations take priority, but review upstream changes for new features or improvements you might want to incorporate.

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

Lines changed: 64 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -49,9 +49,10 @@ commands_paths = [
4949

5050
General workspace metadata. Section: `[workspace]`
5151

52-
| Key | Type | Default | Description |
53-
|-----|------|---------|-------------|
54-
| `name` | string | `"AI Workspace"` | Display name shown in tool UIs |
52+
`name`
53+
: **Type:** string -- **Default:** `"AI Workspace"`
54+
55+
Display name shown in tool UIs
5556

5657
```toml
5758
[workspace]
@@ -64,12 +65,25 @@ name = "My Project Workspace"
6465

6566
Controls repository status reporting at session start. Section: `[repositories]`
6667

67-
| Key | Type | Default | Description |
68-
|-----|------|---------|-------------|
69-
| `default_branch` | string | `"main"` | Fallback branch when not specified in `.gitmodules` |
70-
| `include_workspace_root` | bool | `false` | Include the workspace root repo in session status |
71-
| `template_upstream_url` | string | *(template URL)* | URL for template update notifications |
72-
| `template_upstream_git_remote` | string | `"template-upstream"` | Git remote name for the template upstream |
68+
`default_branch`
69+
: **Type:** string -- **Default:** `"main"`
70+
71+
Fallback branch when not specified in `.gitmodules`
72+
73+
`include_workspace_root`
74+
: **Type:** bool -- **Default:** `false`
75+
76+
Include the workspace root repo in session status
77+
78+
`template_upstream_url`
79+
: **Type:** string -- **Default:** *(template URL)*
80+
81+
URL for template update notifications
82+
83+
`template_upstream_git_remote`
84+
: **Type:** string -- **Default:** `"template-upstream"`
85+
86+
Git remote name for the template upstream
7387

7488
**Common customizations:**
7589

@@ -83,10 +97,15 @@ Controls repository status reporting at session start. Section: `[repositories]`
8397

8498
Configures the script that runs when an AI tool session starts. Section: `[hooks.session_start]`
8599

86-
| Key | Type | Default | Description |
87-
|-----|------|---------|-------------|
88-
| `script` | string | *(required)* | Path to the session-start script |
89-
| `timeout` | int | `120` | Timeout in seconds |
100+
`script`
101+
: **Type:** string -- **Default:** *(required)*
102+
103+
Path to the session-start script
104+
105+
`timeout`
106+
: **Type:** int -- **Default:** `120`
107+
108+
Timeout in seconds
90109

91110
The default script (`.ai-workspace/scripts/session-start.py`) runs two tasks:
92111

@@ -101,11 +120,20 @@ The output is wrapped in `<session-context>` XML tags that agents consume automa
101120

102121
Enable or disable workspace features. Section: `[features]`
103122

104-
| Key | Type | Default | Description |
105-
|-----|------|---------|-------------|
106-
| `skills` | bool | `true` | Enable the skills system (`skills/` directory) |
107-
| `commands` | bool | `true` | Enable the commands system (`commands/` directory) |
108-
| `agent_docs` | bool | `true` | Enable the agent-docs system (`agent-docs/` directory) |
123+
`skills`
124+
: **Type:** bool -- **Default:** `true`
125+
126+
Enable the skills system (`skills/` directory)
127+
128+
`commands`
129+
: **Type:** bool -- **Default:** `true`
130+
131+
Enable the commands system (`commands/` directory)
132+
133+
`agent_docs`
134+
: **Type:** bool -- **Default:** `true`
135+
136+
Enable the agent-docs system (`agent-docs/` directory)
109137

110138
**What happens when you change these:**
111139

@@ -123,9 +151,10 @@ If the directory has user content, pre-commit fails with instructions to manuall
123151

124152
Controls the [Tool Discovery](features/tool-discovery.md) feature. Section: `[tools]`
125153

126-
| Key | Type | Default | Description |
127-
|-----|------|---------|-------------|
128-
| `show_unavailable` | bool | `false` | Show all defined tools with availability status, or only available ones |
154+
`show_unavailable`
155+
: **Type:** bool -- **Default:** `false`
156+
157+
Show all defined tools with availability status, or only available ones
129158

130159
**Behavior:**
131160

@@ -140,11 +169,20 @@ Tools themselves are defined in `agent-tools.yaml` at the repo root, not in this
140169

141170
Controls where skills and commands are distributed for different AI tools. Section: `[distribution]`
142171

143-
| Key | Type | Default | Description |
144-
|-----|------|---------|-------------|
145-
| `skills_paths` | list[str] | `[".opencode/skill"]` | Target directories for skills symlinks |
146-
| `commands_paths` | list[str] | *(see below)* | Target directories for commands |
147-
| `commands_overrides` | dict[str, str] | *(see below)* | Override distribution method for specific command paths |
172+
`skills_paths`
173+
: **Type:** list[str] -- **Default:** `[".opencode/skill"]`
174+
175+
Target directories for skills symlinks
176+
177+
`commands_paths`
178+
: **Type:** list[str] -- **Default:** *(see below)*
179+
180+
Target directories for commands
181+
182+
`commands_overrides`
183+
: **Type:** dict[str, str] -- **Default:** *(see below)*
184+
185+
Override distribution method for specific command paths
148186

149187
**Default command paths:**
150188

‎.ai-workspace/docs/features/agent-docs.md‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -88,11 +88,14 @@ when: |
8888
---
8989
```
9090

91-
| Field | Purpose |
92-
|-------|---------|
93-
| `title` | Human-readable title for the doc |
94-
| `description` | What problems this doc solves (helps agents decide relevance) |
95-
| `when` | Triggering conditions -- tasks, errors, decisions where this helps |
91+
`title`
92+
: Human-readable title for the doc
93+
94+
`description`
95+
: What problems this doc solves (helps agents decide relevance)
96+
97+
`when`
98+
: Triggering conditions -- tasks, errors, decisions where this helps
9699

97100
!!! tip "Frontmatter tip"
98101

‎.ai-workspace/docs/features/temporary-files.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Temporary files
2+
3+
AI agents frequently produce transient artifacts during work -- design documents, investigation logs, intermediate outputs, and other files that don't belong in version control. The workspace provides a dedicated `.tmp/` directory for this, with a helper script that keeps it organized.
4+
5+
## How it works
6+
7+
The `.tmp/` directory is git-ignored (except for its `README.md` and `.gitkeep`). Agents create task-specific subdirectories to isolate artifacts from different tasks, preventing the directory from becoming a dumping ground of mixed files.
8+
9+
The generated `AGENTS.md` instructs agents to use this directory and follow the naming conventions below.
10+
11+
## Creating a task directory
12+
13+
Use the helper script to create a subdirectory:
14+
15+
```bash
16+
uv run .ai-workspace/scripts/mktmpdir.py [name]
17+
```
18+
19+
The script outputs the created path. If a named directory already exists, it returns the existing path.
20+
21+
### Naming strategy
22+
23+
The `name` argument controls how the directory is named:
24+
25+
1. **Work item ID (preferred)** -- Use the canonical identifier when working on tracked items
26+
27+
```bash
28+
uv run .ai-workspace/scripts/mktmpdir.py JIRA-123
29+
uv run .ai-workspace/scripts/mktmpdir.py gh-issue-456
30+
uv run .ai-workspace/scripts/mktmpdir.py pr-789
31+
```
32+
33+
2. **Descriptive name** -- When no work item ID exists, derive a name from the task
34+
35+
```bash
36+
uv run .ai-workspace/scripts/mktmpdir.py fix-api-timeout-retry-logic
37+
```
38+
39+
Include distinguishing details -- `fix-api-timeout-retry-logic` rather than `api-fix`.
40+
41+
3. **Random (default)** -- Omit the name for exploratory or throwaway work
42+
43+
```bash
44+
uv run .ai-workspace/scripts/mktmpdir.py
45+
# Creates: .tmp/20260208-a3f7
46+
```
47+
48+
Generates a `YYYYMMDD-xxxx` directory (date + random hex).
49+
50+
## Subtask coordination
51+
52+
When an agent delegates work to subtasks, passing the directory path keeps all related artifacts together:
53+
54+
- **Delegating subtasks** -- Pass the `.tmp/` subdirectory path so subtask output lands in the same place
55+
- **Coordinating multiple subtasks** -- Create the shared subdirectory before delegating, then pass its path to all subtasks

‎.ai-workspace/docs/features/tool-discovery.md‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,9 @@ Tool Discovery detects installed CLI tools on your system and tells AI agents ab
44

55
!!! info "Requires hook support"
66

7-
Tool discovery context is injected via session hooks, which currently work with [Claude Code](https://code.claude.com/docs/en/hooks) and [OpenCode](https://opencode.ai/docs/plugins/). Other tools can still use the workspace but won't receive automatic tool discovery context.
7+
Tool discovery context is injected via session hooks, which currently work with [Claude Code](https://code.claude.com/docs/en/hooks) and [OpenCode](https://opencode.ai/docs/plugins/).
8+
9+
Other tools can still use the workspace but won't receive automatic tool discovery context.
810

911
## How it works
1012

@@ -73,10 +75,11 @@ In `ai-workspace.toml`:
7375
show_unavailable = false
7476
```
7577

76-
| Value | Behavior |
77-
|-------|----------|
78-
| `false` (default) | Only tools found on PATH are shown to agents |
79-
| `true` | All defined tools are shown with availability status. Useful when you want agents to know what they *could* use if installed. |
78+
`false` (default)
79+
: Only tools found on PATH are shown to agents
80+
81+
`true`
82+
: All defined tools are shown with availability status. Useful when you want agents to know what they *could* use if installed.
8083

8184
## Output format
8285

‎.ai-workspace/docs/getting-started.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,11 @@ Click **"Use this template"** on GitHub to create a new repository. This gives y
2424

2525
!!! note "Why not clone or fork?"
2626

27-
**Cloning** gives you the template's full git history and a remote pointing to the original -- that's not what you want for your own workspace. **Forking** is for contributing back to the template, not for building your own project on top of it. The **"Use this template"** button creates a fresh repo that's entirely yours.
27+
**Cloning** gives you the template's full git history and a remote pointing to the original -- that's not what you want for your own workspace.
28+
29+
**Forking** is for contributing back to the template, not for building your own project on top of it.
30+
31+
The **"Use this template"** button creates a fresh repo that's entirely yours.
2832

2933
### 2. Install dependencies
3034

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,7 @@ workspace/
9696
├── commands/ # Cross-tool AI commands (/command-name)
9797
├── skills/ # Agent skills (SKILL.md files)
9898
├── repositories/ # Git submodules (your projects)
99+
├── .tmp/ # Git-ignored directory for agent work artifacts
99100
├── agent-tools.yaml # CLI tool definitions for discovery
100101
├── ai-workspace.toml # Workspace configuration
101102
├── AGENTS.md # Auto-generated (do not edit directly)

0 commit comments

Comments
 (0)