Skip to content

Commit 0a3c7a5

Browse files
codeaholicguycodeaholicguy
committed
docs: refine agent setup and config reference
1 parent 177404f commit 0a3c7a5

2 files changed

Lines changed: 377 additions & 30 deletions

File tree

‎web/content/docs/11-configuration-file.md‎

Lines changed: 281 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,281 @@
1+
---
2+
title: Configuration File
3+
description: Complete reference for the .ai-devkit.json configuration file used by AI DevKit.
4+
slug: configuration-reference
5+
order: 12
6+
---
7+
8+
AI DevKit stores your project settings in a `.ai-devkit.json` file at your project root. This file is created by `ai-devkit init` and read by most other commands.
9+
10+
There is also an optional global config at `~/.ai-devkit/.ai-devkit.json` for settings that apply across all your projects.
11+
12+
Use this page as a reference for fields inside `.ai-devkit.json`. In most cases, prefer AI DevKit commands such as `ai-devkit init`, `ai-devkit phase`, and `ai-devkit skill add` to update the file for you. Edit the JSON directly only when you need to make a manual change that is not covered by a command.
13+
14+
## Project Config (`.ai-devkit.json`)
15+
16+
### Full Example
17+
18+
```json
19+
{
20+
"version": "0.23.1",
21+
"environments": ["cursor", "claude", "codex"],
22+
"phases": [
23+
"requirements",
24+
"design",
25+
"planning",
26+
"implementation",
27+
"testing"
28+
],
29+
"paths": {
30+
"docs": "docs/ai"
31+
},
32+
"memory": {
33+
"path": ".ai-devkit/memory.db"
34+
},
35+
"skills": {
36+
"registries": {
37+
"codeaholicguy/ai-devkit": "https://github.com/codeaholicguy/ai-devkit.git"
38+
},
39+
"installed": [
40+
{ "registry": "codeaholicguy/ai-devkit", "name": "debug" },
41+
{ "registry": "codeaholicguy/ai-devkit", "name": "dev-lifecycle" }
42+
]
43+
},
44+
"mcpServers": {
45+
"memory": {
46+
"transport": "stdio",
47+
"command": "npx",
48+
"args": ["-y", "@ai-devkit/memory"]
49+
}
50+
},
51+
"createdAt": "2025-12-28T13:35:45.251Z",
52+
"updatedAt": "2026-04-18T10:00:00.000Z"
53+
}
54+
```
55+
56+
### Field Reference
57+
58+
#### `version`
59+
60+
- **Type:** `string`
61+
- **Set automatically** when the config is created.
62+
- Records which AI DevKit version created this file.
63+
- You normally should not edit this field manually.
64+
65+
#### `environments`
66+
67+
- **Type:** array of environment codes
68+
- **Required:** yes
69+
70+
List of AI coding tools to generate configuration files for. Valid values:
71+
72+
| Value | Environment |
73+
|-------|-------------|
74+
| `cursor` | Cursor |
75+
| `claude` | Claude Code |
76+
| `github` | GitHub Copilot |
77+
| `gemini` | Gemini |
78+
| `codex` | Codex |
79+
| `windsurf` | Windsurf |
80+
| `kilocode` | Kilocode |
81+
| `amp` | Amp |
82+
| `opencode` | OpenCode |
83+
| `roo` | Roo |
84+
| `antigravity` | Antigravity |
85+
86+
```json
87+
"environments": ["cursor", "claude"]
88+
```
89+
90+
**Set by:** `ai-devkit init` (interactive or `--environment` flag)
91+
92+
#### `phases`
93+
94+
- **Type:** array of phase names
95+
- **Required:** yes
96+
97+
Stages of the software development lifecycle that AI DevKit creates document templates for. Valid values:
98+
99+
| Value | Description |
100+
|-------|-------------|
101+
| `requirements` | Requirements & Problem Understanding |
102+
| `design` | System Design & Architecture |
103+
| `planning` | Project Planning & Task Breakdown |
104+
| `implementation` | Implementation Guide |
105+
| `testing` | Testing Strategy |
106+
| `deployment` | Deployment Strategy |
107+
| `monitoring` | Monitoring & Observability |
108+
109+
```json
110+
"phases": ["requirements", "design", "planning", "implementation", "testing"]
111+
```
112+
113+
**Set by:** `ai-devkit init`, `ai-devkit phase`
114+
115+
#### `paths`
116+
117+
- **Type:** object
118+
- **Optional**
119+
120+
| Sub-field | Type | Default | Description |
121+
|-----------|------|---------|-------------|
122+
| `docs` | `string` | `docs/ai` | Directory for phase document templates. Relative paths resolve from the project root. |
123+
124+
```json
125+
"paths": {
126+
"docs": "docs/ai"
127+
}
128+
```
129+
130+
**Set by:** `ai-devkit init --docs-dir <path>` or template `paths.docs` field
131+
132+
#### `memory`
133+
134+
- **Type:** object
135+
- **Optional**
136+
137+
| Sub-field | Type | Default | Description |
138+
|-----------|------|---------|-------------|
139+
| `path` | `string` | `.ai-devkit/memory.db` | Path to the SQLite memory database. Absolute paths are used as-is. Relative paths resolve from the directory containing `.ai-devkit.json`. |
140+
141+
```json
142+
"memory": {
143+
"path": ".ai-devkit/memory.db"
144+
}
145+
```
146+
147+
**Read by:** `ai-devkit memory store`, `ai-devkit memory search`, `ai-devkit memory update`
148+
149+
#### `skills`
150+
151+
- **Type:** object or array
152+
- **Optional**
153+
154+
The `skills` field tracks installed skills and custom registries. It supports two formats:
155+
156+
**Object format (recommended):**
157+
158+
If you edit this field manually, use the object format. The array format is supported only for backward compatibility.
159+
160+
```json
161+
"skills": {
162+
"registries": {
163+
"codeaholicguy/ai-devkit": "https://github.com/codeaholicguy/ai-devkit.git"
164+
},
165+
"installed": [
166+
{ "registry": "codeaholicguy/ai-devkit", "name": "debug" }
167+
]
168+
}
169+
```
170+
171+
| Sub-field | Type | Description |
172+
|-----------|------|-------------|
173+
| `registries` | `Record<string, string>` | Maps registry IDs (e.g., `owner/repo`) to Git URLs. Merged with built-in registries. |
174+
| `installed` | array of `{ registry, name }` | List of installed skills. Duplicates are automatically deduplicated. |
175+
176+
**Array format (legacy):**
177+
178+
```json
179+
"skills": [
180+
{ "registry": "codeaholicguy/ai-devkit", "name": "debug" }
181+
]
182+
```
183+
184+
Both formats are accepted. The array format is automatically normalized to the object format.
185+
186+
**Modified by:** `ai-devkit skill add`, `ai-devkit skill remove`, `ai-devkit skill update`, `ai-devkit init --built-in`
187+
188+
#### `mcpServers`
189+
190+
- **Type:** `Record<string, McpServerDefinition>`
191+
- **Optional**
192+
193+
Defines MCP servers that agents can connect to. Each key is the server name. This page covers the `mcpServers` field structure. For setup flow, generated files, and conflict behavior during install, see [Agent Setup — MCP Servers](/docs/agent-setup#mcp-servers).
194+
195+
MCP settings can be stored either by initializing from a template or by editing `.ai-devkit.json` directly. `ai-devkit install` reads the final MCP settings from `.ai-devkit.json` and generates MCP config files only for environments that currently support MCP output.
196+
197+
Every server definition requires a `transport` field set to `stdio`, `http`, or `sse`. The remaining fields depend on the transport type:
198+
199+
**`stdio` transport** — runs a local process:
200+
201+
| Field | Required | Type | Description |
202+
|-------|----------|------|-------------|
203+
| `transport` | Yes | `"stdio"` | |
204+
| `command` | Yes | `string` | Command to execute |
205+
| `args` | No | `string[]` | Command arguments |
206+
| `env` | No | `Record<string, string>` | Environment variables |
207+
208+
```json
209+
"memory": {
210+
"transport": "stdio",
211+
"command": "npx",
212+
"args": ["-y", "@ai-devkit/memory"]
213+
}
214+
```
215+
216+
**`http` or `sse` transport** — connects to a remote server:
217+
218+
| Field | Required | Type | Description |
219+
|-------|----------|------|-------------|
220+
| `transport` | Yes | `"http"` or `"sse"` | |
221+
| `url` | Yes | `string` | Server URL |
222+
| `headers` | No | `Record<string, string>` | HTTP headers (e.g., for authentication) |
223+
224+
```json
225+
"notion": {
226+
"transport": "http",
227+
"url": "https://mcp.notion.com/mcp",
228+
"headers": {
229+
"Authorization": "Bearer your-token"
230+
}
231+
}
232+
```
233+
234+
**Set by:** `ai-devkit init --template` or by editing `.ai-devkit.json` directly
235+
**Read by:** `ai-devkit install`
236+
237+
#### `createdAt` / `updatedAt`
238+
239+
- **Type:** `string` (ISO 8601 timestamp)
240+
- **Set automatically** when the config is created or modified.
241+
- You normally should not edit these fields manually.
242+
243+
## Global Config (`~/.ai-devkit/.ai-devkit.json`)
244+
245+
The global config file has a smaller scope than the project config. It only supports skill registries:
246+
247+
```json
248+
{
249+
"skills": {
250+
"registries": {
251+
"codeaholicguy/ai-devkit": "https://github.com/codeaholicguy/ai-devkit.git",
252+
"my-org/custom-skills": "https://github.com/my-org/custom-skills.git"
253+
}
254+
}
255+
}
256+
```
257+
258+
Use the global config when you want the same custom skill registries available in every project on your machine without copying the same registry entries into each repository.
259+
260+
Global registries are merged with any project-level registries. If the same registry ID exists in both, the project-level entry takes priority.
261+
262+
The global config does **not** support `environments`, `phases`, `paths`, `memory`, or `mcpServers`.
263+
264+
## Which Commands Use the Config
265+
266+
| Command | Creates | Modifies | Reads |
267+
|---------|---------|----------|-------|
268+
| `ai-devkit init` | Yes | Yes | Yes |
269+
| `ai-devkit install` | No | No | Yes |
270+
| `ai-devkit phase` | No | Yes (adds phase) | Yes |
271+
| `ai-devkit skill add` | No | Yes (adds skill) | Yes |
272+
| `ai-devkit skill remove` | No | Yes (removes skill) | Yes |
273+
| `ai-devkit skill update` | No | Yes | Yes |
274+
| `ai-devkit memory *` | No | No | Yes (reads `memory.path`) |
275+
| `ai-devkit lint` | No | No | Yes |
276+
277+
## Related Pages
278+
279+
- [Agent Setup](/docs/agent-setup) — how `init` and `install` use this config
280+
- [Skills](/docs/skills) — managing skills and registries
281+
- [Memory](/docs/memory) — configuring the memory database path

0 commit comments

Comments
 (0)