Skip to content

Commit 8f78715

Browse files
wishket-pjwwishket-pjw
committed
feat(rules): add schema validation and markdown linting
- Add JSON schema for agent definitions - Add markdown linting configuration - Enhance validation script with schema and linting - Add CI/CD validation job - Update documentation close #46
1 parent 8da71fb commit 8f78715

8 files changed

Lines changed: 597 additions & 88 deletions

File tree

‎.ai-rules/schemas/README.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Codingbuddy Schemas
2+
3+
This directory contains JSON schemas for validating AI rule files.
4+
5+
## Available Schemas
6+
7+
### agent.schema.json
8+
9+
Validates agent definition files in `.ai-rules/agents/`.
10+
11+
**Required Fields:**
12+
- `name` - Agent display name
13+
- `description` - Brief description of expertise
14+
- `role` - Role definition with title and expertise
15+
- `context_files` - List of context files to load
16+
17+
**Agent Types:**
18+
19+
| Type | Key Field | Examples |
20+
|------|-----------|----------|
21+
| Developer | `activation` | frontend-developer, backend-developer |
22+
| Reviewer | `activation` | code-reviewer |
23+
| Specialist | `modes` | security-specialist, performance-specialist |
24+
| Other | Neither | devops-engineer |
25+
26+
## Usage
27+
28+
### VS Code Integration
29+
30+
Schemas are automatically applied in VS Code via `.vscode/settings.json`:
31+
32+
```json
33+
{
34+
"json.schemas": [
35+
{
36+
"fileMatch": [".ai-rules/agents/*.json"],
37+
"url": "./.ai-rules/schemas/agent.schema.json"
38+
}
39+
]
40+
}
41+
```
42+
43+
### CLI Validation
44+
45+
```bash
46+
# Validate all agent files
47+
yarn validate:rules
48+
49+
# Validate schema only
50+
yarn validate:rules:schema
51+
```
52+
53+
### Manual Validation with ajv
54+
55+
```bash
56+
npx ajv validate -s .ai-rules/schemas/agent.schema.json -d ".ai-rules/agents/*.json"
57+
```
58+
59+
## Schema Development
60+
61+
When modifying the schema:
62+
63+
1. Update `agent.schema.json`
64+
2. Run validation against all existing files
65+
3. Fix any breaking changes or adjust schema
66+
4. Update this README if needed

‎.ai-rules/schemas/agent.schema.json‎

Lines changed: 258 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,258 @@
1+
{
2+
"$schema": "http://json-schema.org/draft-07/schema#",
3+
"$id": "https://codingbuddy.dev/schemas/agent.schema.json",
4+
"title": "Codingbuddy Agent Definition",
5+
"description": "Schema for AI agent definition files in .ai-rules/agents/",
6+
"type": "object",
7+
"required": ["name", "description", "role", "context_files"],
8+
"properties": {
9+
"name": {
10+
"type": "string",
11+
"description": "Display name of the agent",
12+
"minLength": 1,
13+
"examples": ["Frontend Developer", "Code Reviewer", "Security Specialist"]
14+
},
15+
"description": {
16+
"type": "string",
17+
"description": "Brief description of the agent's purpose and expertise",
18+
"minLength": 10
19+
},
20+
"role": {
21+
"type": "object",
22+
"description": "Agent's role definition including title, expertise, and responsibilities",
23+
"required": ["title"],
24+
"properties": {
25+
"title": {
26+
"type": "string",
27+
"description": "Official role title",
28+
"minLength": 1
29+
},
30+
"expertise": {
31+
"type": "array",
32+
"description": "List of expertise areas",
33+
"items": { "type": "string" },
34+
"minItems": 1
35+
},
36+
"responsibilities": {
37+
"type": "array",
38+
"description": "List of responsibilities",
39+
"items": { "type": "string" }
40+
},
41+
"tech_stack_reference": {
42+
"type": "string",
43+
"description": "Reference to tech stack documentation"
44+
}
45+
},
46+
"additionalProperties": true
47+
},
48+
"context_files": {
49+
"type": "array",
50+
"description": "List of context files to load for this agent",
51+
"items": {
52+
"type": "string",
53+
"pattern": "^\\.ai-rules/.*"
54+
},
55+
"minItems": 1,
56+
"examples": [[".ai-rules/rules/core.md", ".ai-rules/rules/project.md"]]
57+
},
58+
"activation": {
59+
"type": "object",
60+
"description": "Activation configuration for developer/reviewer agents",
61+
"properties": {
62+
"trigger": {
63+
"type": "string",
64+
"description": "Condition that triggers this agent"
65+
},
66+
"rule": {
67+
"type": "string",
68+
"description": "Strict rule for activation"
69+
},
70+
"mandatory_checklist": {
71+
"type": "object",
72+
"description": "Checklist items that must be followed",
73+
"additionalProperties": true
74+
},
75+
"verification_guide": {
76+
"type": "object",
77+
"description": "Guide for verifying checklist items",
78+
"additionalProperties": { "type": "string" }
79+
},
80+
"execution_order": {
81+
"type": "object",
82+
"description": "Order of execution for different modes",
83+
"additionalProperties": {
84+
"type": "array",
85+
"items": { "type": "string" }
86+
}
87+
},
88+
"workflow_integration": {
89+
"type": "object",
90+
"description": "How this agent integrates with workflow"
91+
},
92+
"planning_framework": {
93+
"type": "object",
94+
"description": "Framework for planning mode"
95+
},
96+
"implementation_framework": {
97+
"type": "object",
98+
"description": "Framework for implementation mode"
99+
}
100+
},
101+
"additionalProperties": true
102+
},
103+
"modes": {
104+
"type": "object",
105+
"description": "Mode-specific configuration for specialist agents",
106+
"properties": {
107+
"planning": {
108+
"type": "object",
109+
"description": "Planning mode configuration"
110+
},
111+
"implementation": {
112+
"type": "object",
113+
"description": "Implementation mode configuration"
114+
},
115+
"evaluation": {
116+
"type": "object",
117+
"description": "Evaluation mode configuration"
118+
}
119+
},
120+
"additionalProperties": true
121+
},
122+
"workflow": {
123+
"type": "object",
124+
"description": "Workflow configuration",
125+
"additionalProperties": true
126+
},
127+
"development_philosophy": {
128+
"type": "object",
129+
"description": "Development philosophy and approach",
130+
"additionalProperties": true
131+
},
132+
"code_quality_checklist": {
133+
"type": "array",
134+
"description": "Code quality checklist items",
135+
"items": { "type": "string" }
136+
},
137+
"tdd_cycle": {
138+
"type": "object",
139+
"description": "TDD cycle configuration",
140+
"additionalProperties": true
141+
},
142+
"ai_monitoring": {
143+
"type": "object",
144+
"description": "AI behavior monitoring configuration",
145+
"additionalProperties": true
146+
},
147+
"commit_rules": {
148+
"type": "object",
149+
"description": "Commit rules and discipline",
150+
"additionalProperties": true
151+
},
152+
"design_system": {
153+
"type": "object",
154+
"description": "Design system configuration",
155+
"additionalProperties": true
156+
},
157+
"communication": {
158+
"type": "object",
159+
"description": "Communication preferences",
160+
"properties": {
161+
"language": {
162+
"type": "string",
163+
"description": "Response language preference"
164+
},
165+
"approach": {
166+
"type": "array",
167+
"items": { "type": "string" }
168+
},
169+
"reference_style": {
170+
"type": "string"
171+
},
172+
"emphasis": {
173+
"type": "string"
174+
}
175+
},
176+
"additionalProperties": true
177+
},
178+
"file_naming": {
179+
"type": "object",
180+
"description": "File naming conventions",
181+
"additionalProperties": true
182+
},
183+
"reference": {
184+
"type": "object",
185+
"description": "Reference links and documentation",
186+
"additionalProperties": true
187+
},
188+
"shared_framework": {
189+
"type": "object",
190+
"description": "Shared framework configuration for specialist agents",
191+
"additionalProperties": true
192+
},
193+
"persona": {
194+
"type": "object",
195+
"description": "Agent persona configuration",
196+
"additionalProperties": true
197+
},
198+
"evaluation_framework": {
199+
"type": "object",
200+
"description": "Evaluation framework for reviewer agents",
201+
"additionalProperties": true
202+
},
203+
"evaluation_output_format": {
204+
"type": "object",
205+
"description": "Output format for evaluations",
206+
"additionalProperties": true
207+
},
208+
"evaluation_checklist": {
209+
"type": "object",
210+
"description": "Evaluation checklist",
211+
"additionalProperties": true
212+
},
213+
"improvement_prioritization": {
214+
"type": "object",
215+
"description": "Improvement prioritization rules",
216+
"additionalProperties": true
217+
},
218+
"workflow_integration": {
219+
"type": "object",
220+
"description": "Workflow integration configuration",
221+
"additionalProperties": true
222+
},
223+
"research_requirements": {
224+
"type": "object",
225+
"description": "Research requirements for evidence-based recommendations",
226+
"additionalProperties": true
227+
},
228+
"quality_gates": {
229+
"type": "object",
230+
"description": "Quality gate definitions",
231+
"additionalProperties": true
232+
},
233+
"infrastructure": {
234+
"type": "object",
235+
"description": "Infrastructure configuration (DevOps)",
236+
"additionalProperties": true
237+
},
238+
"best_practices": {
239+
"type": "object",
240+
"description": "Best practices guidelines",
241+
"additionalProperties": true
242+
},
243+
"checklist": {
244+
"oneOf": [
245+
{
246+
"type": "object",
247+
"additionalProperties": true
248+
},
249+
{
250+
"type": "array",
251+
"items": { "type": "string" }
252+
}
253+
],
254+
"description": "General checklist (can be object or array)"
255+
}
256+
},
257+
"additionalProperties": true
258+
}

‎.github/workflows/dev.yml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,31 @@ jobs:
194194
- name: Build
195195
run: yarn build
196196

197+
# ─────────────── Rules Validation ───────────────
198+
rules-validation:
199+
needs: install-dependencies
200+
runs-on: ubuntu-latest
201+
steps:
202+
- name: Checkout code
203+
uses: actions/checkout@v6
204+
205+
- name: Setup node.js
206+
uses: actions/setup-node@v6
207+
with:
208+
node-version: '24'
209+
210+
- name: Validate AI Rules
211+
run: |
212+
echo "📋 Validating JSON Schema..."
213+
yarn dlx ajv-cli validate -s .ai-rules/schemas/agent.schema.json -d ".ai-rules/agents/*.json" --spec=draft7
214+
215+
echo ""
216+
echo "📝 Linting Markdown files..."
217+
yarn dlx markdownlint-cli2 ".ai-rules/**/*.md"
218+
219+
echo ""
220+
echo "✅ All rules validation passed!"
221+
197222
# ─────────────── Security Scan ───────────────
198223
security-check:
199224
needs: install-dependencies

‎.markdownlint.json‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
{
2+
"$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/main/schema/markdownlint-config-schema.json",
3+
"default": true,
4+
"MD001": true,
5+
"MD003": { "style": "atx" },
6+
"MD004": { "style": "dash" },
7+
"MD007": { "indent": 2 },
8+
"MD009": true,
9+
"MD010": true,
10+
"MD012": { "maximum": 2 },
11+
"MD013": false,
12+
"MD022": false,
13+
"MD024": { "siblings_only": true },
14+
"MD025": true,
15+
"MD026": false,
16+
"MD029": { "style": "ordered" },
17+
"MD031": false,
18+
"MD032": false,
19+
"MD033": false,
20+
"MD034": false,
21+
"MD036": false,
22+
"MD040": false,
23+
"MD041": false,
24+
"MD046": { "style": "fenced" },
25+
"MD047": true,
26+
"MD048": { "style": "backtick" },
27+
"MD060": false
28+
}

‎CONTRIBUTING.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,9 @@ yarn test # Unit tests
9898
yarn test:coverage # Coverage (must be 80%+)
9999
yarn circular # Circular dependency check
100100
yarn build # Build verification
101+
102+
# If you modified .ai-rules/ files:
103+
yarn validate:rules # Validate rules structure, schema, and markdown
101104
```
102105

103106
### 5. Submit a Pull Request

0 commit comments

Comments
 (0)