JSON Guidelines
Instructions for writing consistent JSON and JSONC files in this repository.
Formatting
- Formatter: Prettier (configured in devcontainer)
- Indentation: 2 spaces
- Trailing commas: not allowed in
.json files (invalid JSON)
- Line endings: LF (
\n) — enforced by .editorconfig / VS Code settings
- Final newline: always include a trailing newline
JSONC (JSON with Comments)
Files like .vscode/mcp.json, devcontainer.json, and .markdownlint-cli2.jsonc
use JSONC format:
- Use
// for single-line comments explaining non-obvious configuration
- Group related settings with section comments
- Do not use
/* */ block comments
Key Ordering
For configuration files, follow a logical grouping:
package.json: name, version, description, private, scripts,
devDependencies, repository, keywords, author, licensemcp.json: group servers by type (HTTP first, then stdio)devcontainer.json: name, image, features, lifecycle commands,
containerEnv, customizations, mounts, remoteUser
Governance Constraint Files
Files like 04-governance-constraints.json in agent-output/ are generated
by the governance-discovery-subagent:
- Always use an array of policy objects at the root
- Include
displayName, policyDefinitionId, effect, and scope per policy
- Do not manually edit — regenerate via the governance discovery workflow
1---2name: json-guidelines3description: Instructions for writing consistent JSON and JSONC files in this repository.4---56# JSON Guidelines78Instructions for writing consistent JSON and JSONC files in this repository.910## Formatting1112- **Formatter**: Prettier (configured in devcontainer)13- **Indentation**: 2 spaces14- **Trailing commas**: not allowed in `.json` files (invalid JSON)15- **Line endings**: LF (`\n`) — enforced by `.editorconfig` / VS Code settings16- **Final newline**: always include a trailing newline1718## JSONC (JSON with Comments)1920Files like `.vscode/mcp.json`, `devcontainer.json`, and `.markdownlint-cli2.jsonc`21use JSONC format:2223- Use `//` for single-line comments explaining non-obvious configuration24- Group related settings with section comments25- Do not use `/* */` block comments2627## Key Ordering2829For configuration files, follow a logical grouping:3031- **`package.json`**: `name`, `version`, `description`, `private`, `scripts`,32 `devDependencies`, `repository`, `keywords`, `author`, `license`33- **`mcp.json`**: group servers by type (HTTP first, then stdio)34- **`devcontainer.json`**: `name`, `image`, `features`, lifecycle commands,35 `containerEnv`, `customizations`, `mounts`, `remoteUser`3637## Governance Constraint Files3839Files like `04-governance-constraints.json` in `agent-output/` are generated40by the governance-discovery-subagent:4142- Always use an array of policy objects at the root43- Include `displayName`, `policyDefinitionId`, `effect`, and `scope` per policy44- Do not manually edit — regenerate via the governance discovery workflow
tools-only