Summary
Expand Kiro rule coverage from 5 rules to 27 rules to meet S-tier expectations. Currently only steering file validation exists (KIRO-001 to KIRO-004, KR-SK-001).
Context
Research from 50+ sources (deep learning guide + 5 targeted briefs) documented all Kiro file formats. The .kiro/ directory has 5 validatable config surfaces: steering, powers, agent JSON, IDE hooks, and MCP.
Existing rules (5)
| Rule |
What |
Validator |
| KIRO-001 |
Invalid steering inclusion mode |
KiroSteeringValidator |
| KIRO-002 |
Missing required fields for inclusion mode |
KiroSteeringValidator |
| KIRO-003 |
Invalid fileMatchPattern glob |
KiroSteeringValidator |
| KIRO-004 |
Empty steering file |
KiroSteeringValidator |
| KR-SK-001 |
Per-client skill unsupported fields |
PerClientSkillValidator |
New rules to add (22)
Steering (5 new rules - extend KiroSteeringValidator)
| Rule |
Severity |
What |
Source |
| KIRO-005 |
WARNING |
Steering body empty after frontmatter (has --- delimiters but no instructions below) |
kiro.dev/docs/steering - "Include code examples", "Explain reasoning" |
| KIRO-006 |
ERROR |
Secrets/credentials detected in steering file (API keys, tokens, passwords) |
kiro.dev/docs/steering - "Never include secrets" |
| KIRO-007 |
WARNING |
fileMatchPattern present without inclusion: fileMatch (dead field, never used) |
Cross-field logic from KIRO-001/002 |
| KIRO-008 |
WARNING |
Unknown frontmatter field (typo detection - e.g., inclusions instead of inclusion). Valid fields: inclusion, name, description, fileMatchPattern |
kiro.dev/docs/steering |
| KIRO-009 |
WARNING |
Inline file reference #[[file:...]] points to non-existent path |
kiro.dev/docs/steering - advanced syntax |
Powers / POWER.md (4 new rules - new KiroPowerValidator)
| Rule |
Severity |
What |
Source |
| KR-PW-001 |
ERROR |
POWER.md missing required frontmatter fields (name, description, keywords) |
kiro.dev/docs/powers/create - YAML format documented |
| KR-PW-002 |
WARNING |
Empty keywords array in POWER.md (power will never activate - keywords drive activation) |
kiro.dev/docs/powers - activation mechanism |
| KR-PW-003 |
WARNING |
POWER.md body empty (frontmatter only, no Onboarding/Workflows/Troubleshooting/Reference sections) |
kiro.dev/docs/powers/create - expected sections |
| KR-PW-004 |
WARNING |
mcp.json alongside POWER.md has invalid mcpServers structure |
kiro.dev/docs/powers - power structure |
Agent JSON (5 new rules - new KiroAgentValidator)
Agent config lives at ~/.kiro/agents/*.json or .kiro/agents/*.json.
| Rule |
Severity |
What |
Source |
| KR-AG-001 |
WARNING |
Unknown field in agent JSON (valid: name, description, prompt, model, tools, allowedTools, toolAliases, toolsSettings, resources, mcpServers, includeMcpJson, hooks, keyboardShortcut, welcomeMessage) |
kiro.dev/docs/cli/custom-agents/configuration-reference |
| KR-AG-002 |
ERROR |
Invalid resource protocol (must be file:// or skill:// or { type: "knowledgeBase" }) |
kiro.dev/docs/cli/custom-agents/creating |
| KR-AG-003 |
WARNING |
allowedTools contains tool not present in tools array (auto-approve for inaccessible tool) |
kiro.dev/docs/cli/custom-agents/configuration-reference |
| KR-AG-004 |
WARNING |
Invalid model value (known: claude-sonnet-4, claude-sonnet4.5, claude-opus4.5, Auto) |
kiro.dev/docs/cli/custom-agents |
| KR-AG-005 |
INFO |
includeMcpJson: false (default) with no inline mcpServers - agent has zero MCP access |
kiro.dev/docs/cli/custom-agents/configuration-reference |
IDE Hooks - .kiro.hook files (4 new rules - new KiroHookValidator)
IDE hooks are .kiro.hook JSON files in .kiro/hooks/.
| Rule |
Severity |
What |
Source |
| KR-HK-001 |
ERROR |
Invalid hook event type (valid IDE events: fileEdited, fileCreate, fileDelete, promptSubmit, agentStop, preToolUse, postToolUse, manual) |
kiro.dev/docs/hooks/types |
| KR-HK-002 |
ERROR |
File-based hook (fileEdited/fileCreate/fileDelete) missing patterns field |
kiro.dev/docs/hooks/types |
| KR-HK-003 |
ERROR |
Hook has neither runCommand nor askAgent action in then section |
kiro.dev/docs/hooks/actions |
| KR-HK-004 |
WARNING |
Pre/post tool hook missing toolTypes filter (will match all tools) |
kiro.dev/docs/hooks/types |
CLI Hooks in agent JSON (2 new rules - part of KiroAgentValidator)
CLI hooks are defined inline in agent JSON under "hooks" key.
| Rule |
Severity |
What |
Source |
| KR-HK-005 |
ERROR |
Invalid CLI hook event key (valid: agentSpawn, userPromptSubmit, preToolUse, postToolUse, stop) |
kiro.dev/docs/cli/hooks |
| KR-HK-006 |
ERROR |
CLI hook object missing required command field |
kiro.dev/docs/cli/hooks |
MCP in Kiro context (2 new rules - new KiroMcpValidator or extend existing)
| Rule |
Severity |
What |
Source |
| KR-MCP-001 |
ERROR |
MCP server in .kiro/settings/mcp.json missing both command (local) and url (remote) |
kiro.dev/docs/mcp/configuration |
| KR-MCP-002 |
WARNING |
Hardcoded secrets in MCP env values (should use ${VAR} syntax for credential expansion) |
kiro.dev/docs/mcp/configuration |
Validators needed
| Validator |
File Types |
Rules |
| KiroSteeringValidator (extend) |
KiroSteering |
KIRO-005 to KIRO-009 |
| KiroPowerValidator (new) |
KiroPower (new FileType) |
KR-PW-001 to KR-PW-004 |
| KiroAgentValidator (new) |
KiroAgent (new FileType) |
KR-AG-001 to KR-AG-005, KR-HK-005, KR-HK-006 |
| KiroHookValidator (new) |
KiroHook (new FileType) |
KR-HK-001 to KR-HK-004 |
| KiroMcpValidator (new) |
KiroMcp (new FileType) |
KR-MCP-001, KR-MCP-002 |
What was ruled out
- Specs (requirements.md, design.md, tasks.md): Freeform markdown generated by AI, no machine-readable schema. Not worth validating beyond directory structure.
- Settings:
.kiro/settings/ only contains mcp.json. CLI settings are command-based, not file-based. MCP rules cover this.
Acceptance criteria