Need Governance for Agent-Driving Docs
Organizations can enforce coding standards and CI gates but cannot enforce equivalent governance for the Markdown files that shape AI agent behavior.
Take Control Of Your Signals — Become a Naftiko Design Partner Today!
Persona Story:
Riley, the head of APIs, can enforce coding standards and CI gates, but cannot enforce equivalent governance for the Markdown files that shape AI agent behavior.
Problem Context
- Organizations have mature code governance (linting, reviews, CI gates, security scans)
- README/CONTRIBUTING/AGENTS influence how copilots and agents behave
- Doc changes often bypass the same rigor as code changes
Problem Impact
- Silent regressions in agent behavior after doc edits
- Increased security and compliance exposure via unclear or outdated instructions
- Reduced trust in AI tooling as behavior varies repo-to-repo
Naftiko Today
- JSON Schema validation and Spectral ruleset (15 rules) provide automated linting for capability specs, bringing the same rigor as code linting to agent-driving definitions
- The
naftiko validateCLI command can be integrated into CI gates alongside code checks, enforcing governance on every capability change - Executable YAML specs replace freeform Markdown with structured, schema-validated definitions that cannot silently drift in meaning
- VS Code Extension with live validation catches governance violations at authoring time, before they reach a pull request
Naftiko Tomorrow
- OpenAPI-to-Naftiko import (Second Alpha) would let teams migrate from ungoverned doc-driven approaches to schema-validated capability specs
- Control port (Second Alpha) would expose runtime governance status, enabling monitoring of deployed capability compliance
- Resiliency patterns (First Beta) would add enforceable operational governance (retry, circuit breaker, rate limiting) to capability definitions
- K8s operator with Argo CD (Second Alpha) would tie governance validation to deployment pipelines, preventing non-compliant capabilities from reaching production