Skip to content

Commit 34f8f20

Browse files
zahzah
committed
docs(schema): add holistic config schema and dev shell tools
- Add specs/schemas/config.schema.json (draft 2020-12) with shared for enums/shapes - Update specs/configuration.md with Validation section and dev-shell tools, using Just targets - Add specs/schemas/AGENTS.md with validation requirement (just conf-schema-validate) - Update flake.nix: include nodejs and a docson helper; keep taplo/ajv optional - Update Justfile: conf-schema-validate/conf-schema-taplo-check/conf-schema-docs targets (assume nix dev shell) - Update .agents/tasks/2025/08/27-1415-config-schema to first-person human brief - Add TODO notes in codebase-insights for CI validation of configs
1 parent 346d0b3 commit 34f8f20

File tree

7 files changed

+227
-2
lines changed

7 files changed

+227
-2
lines changed

‎.agents/codebase-insights.txt‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,11 @@
2020
- Uses Rake tasks in Rakefile.extras for dependency resolution
2121

2222
## TODOs — CLI Repo Commands Spec (WIP)
23+
24+
## TODOs — Config Schema
25+
- Add CI validation of example TOML configs against `specs/schemas/config.schema.json`.
26+
- Consider an `aw config validate` command and `aw schema print config` for tooling.
27+
- Track enum reuse centrally in `$defs`; extend with delivery modes, runtimes, auth sources as they are added to the CLI spec.
2328
- Clarify final command names: typos in draft use "insturctions"; spec adopts `aw repo instructions create` and `aw repo instructions link`. Consider alias `aw repo create-agent-instruction-symlinks` for backwards compatibility with docs.
2429
- Define exact editor discovery order and env/config keys reused by `aw repo init` when prompting for project description.
2530
- Specify JSON schemas for `repo init`, `instructions create`, `instructions link`, `repo check`, and `health` in a central place (currently summarized inline in cli-spec.md).

‎.agents/tasks/2025/08/27-1415-config-schema‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
I want a single, holistic configuration schema for Agents‑Workflow.
2+
3+
TOML maps closely to JSON, so using JSON Schema to validate TOML (parse TOML → JSON → validate) seems practical. Please keep it DRY by defining shared enums and shapes once (e.g., supported agents, runtimes, task runners, log levels, modes, etc.) and reusing them across the configuration.
4+
5+
We should have one schema for the entire configuration that the CLI can validate against, and editors (like Taplo) can use for IntelliSense.
6+
7+
Also, I’d like JSON Schema validation and review tools available in the dev shell: taplo-cli and ajv-cli; and I’d like to try Docson for viewing the schema.

‎Justfile‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,20 @@ lint-fix:
1414
# Build and publish the gem
1515
publish-gem:
1616
gem build agent-task.gemspec && gem push agent-task-*.gem
17+
18+
# Validate all JSON Schemas with ajv (meta-schema compile)
19+
conf-schema-validate:
20+
set -euo pipefail
21+
for f in specs/schemas/*.json; do
22+
echo Validating $$f
23+
ajv compile -s "$$f"
24+
done
25+
echo All schemas valid.
26+
27+
# Check TOML files with Taplo (uses schema mapping if configured)
28+
conf-schema-taplo-check:
29+
taplo check
30+
31+
# Serve schema docs locally with Docson (opens http://localhost:3000)
32+
conf-schema-docs:
33+
docson -d specs/schemas

‎flake.nix‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -70,14 +70,22 @@
7070
pkgs.git
7171
pkgs.fossil
7272
pkgs.mercurial
73+
pkgs.nodejs # for npx-based docson helper
7374

7475
# AI Coding Assistants (latest versions from nixpkgs-unstable)
7576
pkgs.goose-cli # Goose AI coding assistant
7677
pkgs.claude-code # Claude Code - agentic coding tool
7778
pkgs.gemini-cli # Gemini CLI
7879
pkgs.codex # OpenAI Codex CLI (Rust implementation)
7980
pkgs.opencode # OpenCode AI coding assistant
80-
] ++ pkgs.lib.optionals isLinux [
81+
]
82+
# Optional schema/validation tooling (only if available in this nixpkgs)
83+
++ (builtins.filter (x: x != null) [
84+
(if pkgs ? taplo then pkgs.taplo else null)
85+
(if (builtins.hasAttr "nodePackages" pkgs) && (builtins.hasAttr "ajv-cli" pkgs.nodePackages)
86+
then pkgs.nodePackages."ajv-cli" else null)
87+
])
88+
++ pkgs.lib.optionals isLinux [
8189
# Linux-only filesystem utilities for snapshot functionality
8290
pkgs.zfs # ZFS utilities for copy-on-write snapshots
8391
pkgs.btrfs-progs # Btrfs utilities for subvolume snapshots
@@ -88,6 +96,9 @@
8896

8997
shellHook = ''
9098
echo "Agent workflow development environment loaded"
99+
# Provide a convenience function to launch Docson without global install
100+
docson () { npx -y docson "$@"; }
101+
echo "Tip: run: docson -d ./specs/schemas # then open http://localhost:3000"
91102
'';
92103
};
93104
});

‎specs/configuration.md‎

Lines changed: 76 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
* Motivation and support for tracking the origin of each configuration value, with use cases such as: debug-level log reporting, enforced setting explanation, and editor pre-fill mes
1010
sages.
1111

12-
Layered configuration supports system, user, project, and project-user scopes. Values can also be supplied via environment variables and CLI flags. See `docs/cli-spec.md` for flag mappings.
12+
Layered configuration supports system, user, project, and project-user scopes. Values can also be supplied via environment variables and CLI flags. See `specs/cli-spec.md` for flag mappings.
1313

1414
### Keys
1515

@@ -23,3 +23,78 @@ Layered configuration supports system, user, project, and project-user scopes. V
2323
- CLI flags override environment, which override project-user, project, user, then system scope.
2424
- On Windows, `~/.config` takes precedence over `%APPDATA%` only when both are present.
2525
- The CLI can read, write, and explain config values via `aw config`.
26+
27+
### Validation
28+
29+
- The configuration file format is TOML, validated against a single holistic JSON Schema:
30+
- Schema: `specs/schemas/config.schema.json` (draft 2020-12)
31+
- Method: parse TOML → convert to a JSON data model → validate against the schema
32+
- Editors: tools like Taplo can use the JSON Schema to provide completions and diagnostics
33+
34+
- DRY definitions: the schema uses `$defs` for shared enums and shapes reused across the CLI (e.g., `Mode`, `Multiplexer`, `Vcs`, `DevEnv`, `TaskRunner`, `AgentName`, `SupportedAgents`).
35+
36+
Tools in the dev shell:
37+
38+
- `taplo` (taplo-cli): TOML validation with JSON Schema mapping
39+
- `ajv` (ajv-cli): JSON Schema validator for JSON instances
40+
- `docson` (via shell function): local schema viewer using `npx` (no global install)
41+
42+
Examples (use Just targets inside the Nix dev shell):
43+
44+
```bash
45+
# Validate all JSON Schemas (meta-schema compile)
46+
just conf-schema-validate
47+
48+
# Check TOML files with Taplo
49+
just conf-schema-taplo-check
50+
51+
# Preview the schemas with Docson (serves http://localhost:3000)
52+
just conf-schema-docs
53+
```
54+
55+
Tip: from the host without entering the shell explicitly, you can run any target via:
56+
57+
```bash
58+
nix develop --command just conf-schema-validate
59+
```
60+
61+
Example TOML (partial):
62+
63+
```toml
64+
logLevel = "info"
65+
mode = "auto"
66+
67+
[tui]
68+
defaultMode = "auto"
69+
70+
[terminal]
71+
multiplexer = "tmux"
72+
73+
[editor]
74+
default = "nvim"
75+
76+
[network]
77+
apiUrl = "https://aw.example.internal/api"
78+
79+
[browserAutomation]
80+
enabled = true
81+
profile = "work-codex"
82+
chatgptUsername = "[email protected]"
83+
84+
[codex]
85+
workspace = "main"
86+
87+
[repo]
88+
supportedAgents = "all" # or ["codex","claude","cursor"]
89+
90+
[repo.init]
91+
vcs = "git"
92+
devenv = "nix"
93+
devcontainer = true
94+
direnv = true
95+
taskRunner = "just"
96+
```
97+
98+
Notes:
99+
- `supportedAgents` accepts "all" or an explicit array of agent names; the CLI may normalize this value internally.
100+
- `devenv` accepts values like `nix`, `spack`, `bazel`, `none`/`no`, or `custom`.

‎specs/schemas/AGENTS.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
All changes to the schema must be validated by running:
2+
3+
`just conf-schema-validate`

‎specs/schemas/config.schema.json‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://blocksense.dev/schemas/agents-workflow/config.schema.json",
4+
"title": "Agents-Workflow Configuration",
5+
"type": "object",
6+
"additionalProperties": false,
7+
"$defs": {
8+
"LogLevel": { "type": "string", "enum": ["debug", "info", "warn", "error"] },
9+
"Mode": { "type": "string", "enum": ["auto", "local", "rest"] },
10+
"Multiplexer": { "type": "string", "enum": ["tmux", "zellij", "screen"] },
11+
"Vcs": { "type": "string", "enum": ["git", "hg", "bzr", "fossil"] },
12+
"DevEnv": { "type": "string", "enum": ["nix", "spack", "bazel", "none", "no", "custom"] },
13+
"TaskRunner": { "type": "string", "enum": ["just", "make"] },
14+
"AgentName": {
15+
"type": "string",
16+
"enum": [
17+
"generic",
18+
"codex",
19+
"copilot",
20+
"claude",
21+
"gemini",
22+
"cursor",
23+
"windsurf",
24+
"zed",
25+
"cline",
26+
"roo",
27+
"jetbrains",
28+
"openhands"
29+
]
30+
},
31+
"SupportedAgents": {
32+
"oneOf": [
33+
{ "type": "string", "const": "all" },
34+
{ "type": "array", "items": { "$ref": "#/$defs/AgentName" }, "uniqueItems": true }
35+
]
36+
},
37+
"YesNo": { "type": "boolean" },
38+
"Uri": { "type": "string", "format": "uri" }
39+
},
40+
"properties": {
41+
"tui": {
42+
"type": "object",
43+
"additionalProperties": false,
44+
"properties": {
45+
"defaultMode": { "$ref": "#/$defs/Mode" }
46+
}
47+
},
48+
"terminal": {
49+
"type": "object",
50+
"additionalProperties": false,
51+
"properties": {
52+
"multiplexer": { "$ref": "#/$defs/Multiplexer" }
53+
}
54+
},
55+
"editor": {
56+
"type": "object",
57+
"additionalProperties": false,
58+
"properties": {
59+
"default": { "type": "string", "minLength": 1 }
60+
}
61+
},
62+
"network": {
63+
"type": "object",
64+
"additionalProperties": false,
65+
"properties": {
66+
"apiUrl": { "$ref": "#/$defs/Uri" }
67+
}
68+
},
69+
"browserAutomation": {
70+
"type": "object",
71+
"additionalProperties": false,
72+
"properties": {
73+
"enabled": { "type": "boolean" },
74+
"profile": { "type": "string" },
75+
"chatgptUsername": { "type": "string" }
76+
}
77+
},
78+
"codex": {
79+
"type": "object",
80+
"additionalProperties": false,
81+
"properties": {
82+
"workspace": { "type": "string" }
83+
}
84+
},
85+
"repo": {
86+
"type": "object",
87+
"additionalProperties": false,
88+
"properties": {
89+
"supportedAgents": { "$ref": "#/$defs/SupportedAgents" },
90+
"init": {
91+
"type": "object",
92+
"additionalProperties": false,
93+
"properties": {
94+
"vcs": { "$ref": "#/$defs/Vcs" },
95+
"devenv": { "$ref": "#/$defs/DevEnv" },
96+
"devcontainer": { "$ref": "#/$defs/YesNo" },
97+
"direnv": { "$ref": "#/$defs/YesNo" },
98+
"taskRunner": { "$ref": "#/$defs/TaskRunner" }
99+
}
100+
}
101+
}
102+
},
103+
"logLevel": { "$ref": "#/$defs/LogLevel" },
104+
"mode": { "$ref": "#/$defs/Mode" }
105+
}
106+
}
107+

0 commit comments

Comments
 (0)