Skip to content

Commit 5f5a4dd

Browse files
MichaelYochpazMichaelYochpaz
committed
new stuff
1 parent a124234 commit 5f5a4dd

20 files changed

Lines changed: 778 additions & 20 deletions

‎.ai-workspace/docs/ci-recommendations.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# CI Recommendations
2+
3+
This template does not ship CI workflows for template users, since teams use different CI systems (GitHub Actions, GitLab CI, etc.). Below are recommended CI steps and example configurations.
4+
5+
## Recommended CI Steps
6+
7+
<!-- TODO: Explain why each step matters -->
8+
9+
1. **Install dependencies** — `uv sync`
10+
2. **Run pre-commit checks** — `uv run pre-commit run --all-files`
11+
3. **Run session-start script** _(optional)_ — `uv run python .ai-workspace/scripts/session-start.py` as a smoke test
12+
13+
## GitHub Actions Example
14+
15+
<!-- TODO: Adapt and test this example -->
16+
17+
```yaml
18+
name: ci
19+
on:
20+
push:
21+
branches: [main]
22+
pull_request:
23+
24+
jobs:
25+
check:
26+
runs-on: ubuntu-latest
27+
steps:
28+
- uses: actions/checkout@v4
29+
with:
30+
submodules: recursive
31+
- uses: astral-sh/setup-uv@v6
32+
- run: uv sync
33+
- run: uv run pre-commit run --all-files
34+
```
35+
36+
## GitLab CI Example
37+
38+
<!-- TODO: Adapt and test this example -->
39+
40+
```yaml
41+
check:
42+
image: python:3.12
43+
before_script:
44+
- pip install uv
45+
- uv sync
46+
- git submodule update --init --recursive
47+
script:
48+
- uv run pre-commit run --all-files
49+
```
50+
51+
## Notes
52+
53+
<!-- TODO: Additional guidance -->
54+
<!-- Points to cover: -->
55+
<!-- - Pre-commit hooks catch most issues (alignment, validation, transpilation) -->
56+
<!-- - Submodule checkout may require SSH keys or tokens in CI -->
57+
<!-- - Consider caching uv/pip dependencies for faster builds -->

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

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Configuration
2+
3+
The workspace is configured via `ai-workspace.toml` at the repository root.
4+
5+
A JSON Schema is auto-generated at `.ai-workspace/schema.json` for editor autocomplete.
6+
7+
## `[workspace]`
8+
9+
| Key | Type | Default | Description |
10+
|-----|------|---------|-------------|
11+
| `name` | string | `"AI Workspace"` | Workspace display name |
12+
13+
## `[sync]`
14+
15+
<!-- TODO: Explain each option with context on when/why to change it -->
16+
17+
| Key | Type | Default | Description |
18+
|-----|------|---------|-------------|
19+
| `skip_on_uncommitted_changes` | bool | `true` | Skip submodules with uncommitted changes during sync (`false` = fail) |
20+
| `default_branch` | string | `"main"` | Fallback branch if not specified in `.gitmodules` |
21+
| `template_upstream_url` | string | _(template URL)_ | URL for template update notifications. Set empty to disable. |
22+
| `template_upstream_git_remote` | string | `"template-upstream"` | Git remote name for the template upstream |
23+
24+
## `[hooks.session_start]`
25+
26+
<!-- TODO: Explain the session start hook concept -->
27+
28+
| Key | Type | Default | Description |
29+
|-----|------|---------|-------------|
30+
| `script` | string | _(required)_ | Path to the script to run at session start |
31+
| `timeout` | int | `120` | Timeout in seconds |
32+
33+
## `[features]`
34+
35+
<!-- TODO: Explain what happens when features are enabled/disabled -->
36+
<!-- Points to cover: -->
37+
<!-- - Enabling creates the directory with a README -->
38+
<!-- - Disabling removes the directory IF empty -->
39+
<!-- - If directory has content, pre-commit fails with instructions -->
40+
41+
| Key | Type | Default | Description |
42+
|-----|------|---------|-------------|
43+
| `skills` | bool | `true` | Enable the skills system |
44+
| `commands` | bool | `true` | Enable the commands system |
45+
| `agent_docs` | bool | `true` | Enable the agent-docs system |
46+
47+
## `[tools]`
48+
49+
<!-- TODO: Explain tool discovery and link to tool-discovery feature page -->
50+
51+
| Key | Type | Default | Description |
52+
|-----|------|---------|-------------|
53+
| `show_unavailable` | bool | `false` | Show all defined tools with availability status, or only available ones |
54+
55+
## `[distribution]`
56+
57+
<!-- TODO: Explain how distribution works and when to customize paths -->
58+
59+
| Key | Type | Default | Description |
60+
|-----|------|---------|-------------|
61+
| `skills_paths` | list[str] | `[".opencode/skill"]` | Target directories for skills symlinks |
62+
| `commands_paths` | list[str] | _(IDE dirs)_ | Target directories for commands |
63+
64+
## Example Configuration
65+
66+
```toml
67+
[workspace]
68+
name = "AI Workspace"
69+
70+
[sync]
71+
skip_on_uncommitted_changes = true
72+
default_branch = "main"
73+
template_upstream_url = "https://github.com/MichaelYochpaz/ai-workspace-template.git"
74+
template_upstream_git_remote = "template-upstream"
75+
76+
[hooks.session_start]
77+
script = ".ai-workspace/scripts/session-start.py"
78+
timeout = 120
79+
80+
[features]
81+
skills = true
82+
commands = true
83+
agent_docs = true
84+
85+
[tools]
86+
show_unavailable = false
87+
88+
[distribution]
89+
skills_paths = [".opencode/skill"]
90+
commands_paths = [
91+
".roo/commands",
92+
".claude/commands",
93+
".cursor/commands",
94+
".opencode/command",
95+
]
96+
```

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

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Agent Docs
2+
3+
Agent Docs are modular, task-focused documentation files optimized for AI agent consumption. They provide context and instructions that agents read when performing specific tasks.
4+
5+
## How It Works
6+
7+
<!-- TODO: Explain the discovery and injection mechanism -->
8+
<!-- Points to cover: -->
9+
<!-- - Each doc lives in agent-docs/<name>/ with metadata.yaml + <name>.md -->
10+
<!-- - metadata.yaml provides name, description, when_to_read -->
11+
<!-- - Pre-commit auto-generates the listing in AGENTS.md -->
12+
<!-- - Agents review the listing and read docs relevant to their task -->
13+
14+
## Directory Structure
15+
16+
```
17+
agent-docs/
18+
└── <topic>/
19+
├── metadata.yaml # Discovery metadata
20+
└── <topic>.md # Documentation content
21+
```
22+
23+
## Creating a Document
24+
25+
### 1. Create the Directory
26+
27+
```bash
28+
mkdir -p agent-docs/<topic>
29+
```
30+
31+
### 2. Write `metadata.yaml`
32+
33+
<!-- TODO: Explain each field with guidance on writing effective metadata -->
34+
<!-- Points to cover: -->
35+
<!-- - name: Human-readable title -->
36+
<!-- - description: What problems this doc solves (not a table of contents) -->
37+
<!-- - when_to_read: Triggering conditions — tasks, errors, decisions -->
38+
39+
```yaml
40+
name: My Documentation
41+
description: |
42+
What this doc covers and what problems it solves.
43+
when_to_read: |
44+
When performing X tasks or encountering Y situations.
45+
```
46+
47+
### 3. Write the Documentation
48+
49+
<!-- TODO: Link to or summarize the writing guidelines from agent-docs/README.md -->
50+
<!-- Key principles: -->
51+
<!-- - Accuracy first — verify facts before writing -->
52+
<!-- - Token efficiency — concise but complete -->
53+
<!-- - Focused scope — one topic per document -->
54+
<!-- - Self-contained — don't reference other agent-docs -->
55+
<!-- - Actionable — file paths, commands, decision trees -->
56+
57+
Create `agent-docs/<topic>/<topic>.md` with the documentation content.
58+
59+
## Best Practices
60+
61+
<!-- TODO: Expand with examples -->
62+
63+
- Keep documents focused on a single topic
64+
- Use generic examples with placeholders instead of version-specific content
65+
- Structure content with clear headings for scannability
66+
- Include concrete commands and file paths
67+
- Verify accuracy by reading source code before writing

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

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Commands
2+
3+
Commands are reusable AI prompts invoked by users (e.g., `/my-command`) and executed by AI agents. They work across multiple tools through a "superset frontmatter" pattern.
4+
5+
## How It Works
6+
7+
<!-- TODO: Explain the superset frontmatter concept -->
8+
<!-- Points to cover: -->
9+
<!-- - Single command.md file contains metadata for ALL supported tools -->
10+
<!-- - Each tool's parser ignores keys it doesn't recognize -->
11+
<!-- - Distribution via symlinks (most tools) or transpilation (Cursor) -->
12+
<!-- - User invokes via /command-name, agent receives the prompt -->
13+
14+
## Directory Structure
15+
16+
```
17+
commands/
18+
└── <command-name>/
19+
└── command.md # Frontmatter + prompt content
20+
```
21+
22+
## Creating a Command
23+
24+
<!-- TODO: Step-by-step with example -->
25+
<!-- Points to cover: -->
26+
<!-- - Create directory and command.md -->
27+
<!-- - Write superset frontmatter (description, tool-specific fields) -->
28+
<!-- - Write the prompt body using polyglot patterns -->
29+
<!-- - Run transpile script to distribute -->
30+
31+
### Superset Frontmatter
32+
33+
```yaml
34+
---
35+
# Universal
36+
description: "Brief description for UI menus"
37+
38+
# Roo Code
39+
argument-hint: "<optional_argument>"
40+
41+
# Claude Code
42+
allowed-tools: ["read_file", "list_files"]
43+
44+
# Cursor
45+
globs: ["**/*.ts", "**/*.tsx"]
46+
alwaysApply: false
47+
---
48+
```
49+
50+
### Writing Polyglot Prompts
51+
52+
<!-- TODO: Guidelines for cross-tool compatibility -->
53+
<!-- Points to cover: -->
54+
<!-- - Use natural language for tool invocation ("Use your terminal..." not !bash) -->
55+
<!-- - Avoid version-specific content -->
56+
<!-- - Avoid tool-specific syntax unless necessary -->
57+
58+
## Distribution
59+
60+
```bash
61+
uv run .ai-workspace/scripts/transpile-commands.py
62+
```
63+
64+
## Supported Tools
65+
66+
| Tool | Distribution | Notes |
67+
|------|-------------|-------|
68+
| Claude Code | Symlink | Ignores unknown YAML keys |
69+
| Cursor | Transpile | Frontmatter stripped to avoid issues |
70+
| OpenCode | Symlink | Uses `.opencode/command/` (singular) |
71+
| Roo Code | Symlink | Ignores unknown YAML keys |

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

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Skills
2+
3+
Skills are reusable agent capabilities following the [Agent Skills specification](https://agentskills.io/specification). They provide structured instructions and scripts that agents load on-demand when user requests match.
4+
5+
## How It Works
6+
7+
<!-- TODO: Explain the progressive disclosure model -->
8+
<!-- Points to cover: -->
9+
<!-- - Discovery: agents load name + description at startup (~100 tokens each) -->
10+
<!-- - Activation: when a request semantically matches, full SKILL.md is loaded -->
11+
<!-- - Resources: scripts and references loaded on demand -->
12+
<!-- - This minimizes context usage while keeping capabilities available -->
13+
14+
## Directory Structure
15+
16+
```
17+
skills/
18+
└── <skill-name>/
19+
├── SKILL.md # Required: Frontmatter + instructions
20+
├── scripts/ # Optional: Executable scripts
21+
├── tests/ # Optional: Test files
22+
├── references/ # Optional: Additional documentation
23+
└── assets/ # Optional: Templates, data files
24+
```
25+
26+
## Creating a Skill
27+
28+
<!-- TODO: Step-by-step walkthrough -->
29+
<!-- Points to cover: -->
30+
<!-- - Create directory: mkdir -p skills/<name>/scripts -->
31+
<!-- - Create SKILL.md with frontmatter (name, description, allowed-tools) -->
32+
<!-- - Write instructions in the body -->
33+
<!-- - Add scripts with PEP 723 inline dependencies -->
34+
<!-- - Run transpile script to validate and distribute -->
35+
36+
### SKILL.md Format
37+
38+
```markdown
39+
---
40+
name: my-skill
41+
description: Action + object + context. Use when X, Y, or Z.
42+
allowed-tools: Bash(python:*) Bash(uv:*) Read
43+
---
44+
45+
# My Skill
46+
47+
Instructions for the agent...
48+
```
49+
50+
### Frontmatter Fields
51+
52+
| Field | Required | Description |
53+
|-------|----------|-------------|
54+
| `name` | Yes | Lowercase `a-z`, `0-9`, `-` only. Must match directory name. |
55+
| `description` | Yes | What it does AND when to use it (max 1024 chars). |
56+
| `allowed-tools` | No | Space-delimited pre-approved tool patterns. |
57+
58+
## Distribution
59+
60+
<!-- TODO: Explain the transpile/symlink mechanism -->
61+
<!-- Points to cover: -->
62+
<!-- - skills/ is source of truth -->
63+
<!-- - Transpile script validates and symlinks to target directories -->
64+
<!-- - Distribution targets configured in ai-workspace.toml [distribution].skills_paths -->
65+
66+
```bash
67+
uv run .ai-workspace/scripts/transpile-skills.py # Validate + distribute
68+
uv run .ai-workspace/scripts/transpile-skills.py --validate # Validate only
69+
```
70+
71+
## Supported Tools
72+
73+
| Tool | Discovery Path | Notes |
74+
|------|----------------|-------|
75+
| Claude Code | `.claude/skills/` | Native discovery; symlinked from `skills/` |
76+
| OpenCode | `.opencode/skill/` | Native discovery; symlinked via transpile |
77+
| Roo Code | `skills/` | Native discovery |

0 commit comments

Comments
 (0)