Agent-Skills.md

Agent Skills: doc-ctr-validator

Validate Data Contracts (CTR) documents against Layer 8 schema standards

UncategorizedID: vladm3105/aidoc-flow-framework/doc-ctr-validator
93

Install this agent skill to your local

pnpm dlx add-skill https://github.com/vladm3105/aidoc-flow-framework/tree/HEAD/.claude/skills/doc-ctr-validator

Skill Files

Browse the full folder contents for doc-ctr-validator.

Download Skill

Loading file tree…

.claude/skills/doc-ctr-validator/SKILL.md

Skill Metadata

Name
doc-ctr-validator
Description
Validate Data Contracts (CTR) documents against Layer 8 schema standards

doc-ctr-validator

Validate Data Contracts (CTR) documents against Layer 8 schema standards.

Activation

Invoke when user requests validation of CTR documents or after creating/modifying CTR artifacts.

Validation Schema Reference

Schema: ai_dev_ssd_flow/08_CTR/CTR_SCHEMA.yaml Layer: 8 Artifact Type: CTR

Validation Checklist

0. Folder Structure Validation (BLOCKING)

Nested Folder Rule: ALL CTR documents MUST be in nested folders regardless of size.

Required Structure:

| CTR Type | Required Location | |----------|-------------------| | Dual-File | docs/08_CTR/CTR-NN_{slug}/CTR-NN_{slug}.md + CTR-NN_{slug}.yaml |

Validation:

1. Check document is inside a nested folder: docs/08_CTR/CTR-NN_{slug}/
2. Verify folder name matches CTR ID pattern: CTR-NN_{slug}
3. Verify both .md and .yaml files exist with matching names
4. Parent path must be: docs/08_CTR/

Example Valid Structure:

docs/08_CTR/
├── CTR-01_f1_iam_api/
│   ├── CTR-01_f1_iam_api.md       ✓ Valid
│   ├── CTR-01_f1_iam_api.yaml     ✓ Valid (companion schema)
│   ├── CTR-01.R_review_report_v001.md
│   └── .drift_cache.json
├── CTR-02_f2_session_api/
│   ├── CTR-02_f2_session_api.md   ✓ Valid
│   └── CTR-02_f2_session_api.yaml ✓ Valid

Invalid Structure:

docs/08_CTR/
├── CTR-01_f1_iam_api.md           ✗ NOT in nested folder
├── CTR-01_f1_iam_api.yaml         ✗ NOT in nested folder

Error Codes:

| Code | Severity | Description | |------|----------|-------------| | CTR-E020 | ERROR | CTR not in nested folder (BLOCKING) | | CTR-E021 | ERROR | Folder name doesn't match CTR ID | | CTR-E022 | ERROR | File name doesn't match folder name | | VAL-H001 | ERROR | Drift cache missing hash for upstream document | | VAL-H002 | ERROR | Invalid hash format (must be sha256:<64 hex chars>) |

This check is BLOCKING - CTR must pass folder structure validation before other checks proceed.

1. Metadata Validation

Required custom_fields:
  - document_type: ["ctr", "template"]
  - artifact_type: "CTR"
  - layer: 8
  - architecture_approaches: [array format]
  - priority: ["primary", "shared", "fallback"]
  - development_status: ["active", "draft", "deprecated", "reference"]

Required tags:
  - ctr (or ctr-template)
  - layer-8-artifact

Forbidden tag patterns:
  - "^ctr-document$"
  - "^contract$"
  - "^api-contract$"
  - "^ctr-\\d{3}$"

2. Structure Validation (Dual-File Format)

File Format:

  • Documentation: .md file
  • Schema: .yaml file
  • Pattern: CTR-NNN_descriptive_name.md + CTR-NNN_descriptive_name.yaml

Required Sections (12 Sections + 2 Optional Appendices):

| Section | Title | Required | |---------|-------|----------| | Title | # CTR-NN: Title (H1) | MANDATORY | | 1 | Document Control | MANDATORY | | 2 | Context | MANDATORY | | 3 | Contract Definition | MANDATORY | | 4 | Requirements Satisfied | MANDATORY | | 5 | Interface Definition | MANDATORY | | 6 | Error Handling | MANDATORY | | 7 | Quality Attributes | MANDATORY | | 8 | Versioning Strategy | MANDATORY | | 9 | Examples | MANDATORY | | 10 | Verification | MANDATORY | | 11 | Traceability | MANDATORY | | 12 | References | MANDATORY |

Optional Appendices: | Section | Title | Required | |---------|-------|----------| | Appendix A | Alternatives Considered | OPTIONAL | | Appendix B | Implementation Notes | OPTIONAL |

Document Control Required Fields:

  • Project Name
  • Document Version
  • Date
  • Document Owner
  • Prepared By
  • Status

3. Content Validation

Status Values:

  • Draft
  • In Review
  • Approved
  • Active
  • Deprecated

Communication Patterns:

  • Synchronous: REST, gRPC, GraphQL
  • Asynchronous: Event-driven, Message Queue, Pub/Sub

Error Code Format:

  • Pattern: ^[A-Z_]+$
  • Examples: INVALID_INPUT, INSUFFICIENT_DATA, RATE_LIMITED, SERVICE_UNAVAILABLE, INTERNAL_ERROR

Versioning:

  • Format: MAJOR.MINOR.PATCH (Semantic versioning)

YAML Schema Requirements:

  • OpenAPI 3.x or JSON Schema format
  • Required: info (title, version, description), paths, components/schemas
  • All endpoints must have request and response schemas

4. Traceability Validation

Layer 8 Cumulative Tags:

  • @brd: BRD.NN.EE.SS (required)
  • @prd: PRD.NN.EE.SS (required)
  • @ears: EARS.NN.EE.SS (required)
  • @bdd: BDD.NN.EE.SS (required)
  • @adr: ADR-NN (required)
  • @sys: SYS.NN.EE.SS (required)
  • @req: REQ.NN.EE.SS (required)

Downstream Expected:

  • SPEC documents
  • TASKS documents
  • Code (src/...)

Same-Type References:

  • @related-ctr: CTR-NN
  • @depends-ctr: CTR-NN

Error Codes

| Code | Severity | Description | |------|----------|-------------| | CTR-E001 | error | Missing required tag 'ctr' | | CTR-E002 | error | Missing required tag 'layer-8-artifact' | | CTR-E003 | error | Invalid document_type | | CTR-E004 | error | Invalid architecture_approaches format | | CTR-E005 | error | Forbidden tag pattern detected | | CTR-E006 | error | Missing required section | | CTR-E007 | error | Multiple H1 headings detected | | CTR-E008 | error | Section numbering not sequential (1-12) | | CTR-E009 | error | Document Control missing required fields | | CTR-E010 | error | Missing companion YAML schema file | | CTR-E011 | error | YAML schema is not valid OpenAPI 3.x or JSON Schema | | CTR-E012 | error | Missing request/response schemas for endpoints | | CTR-E013 | error | Missing Error Handling section | | CTR-E014 | warning | File name does not match format | | CTR-E015 | error | Contract Definition missing Provider/Consumer | | CTR-E016 | error | Error Codes table missing | | CTR-W001 | warning | Missing Context Problem Statement | | CTR-W002 | warning | Missing success/failure examples | | CTR-W003 | warning | Missing upstream tags (require 7) | | CTR-W004 | warning | Missing Versioning Strategy Version Policy | | CTR-W005 | warning | Error responses not defined in YAML schema | | CTR-W006 | warning | Missing contract testing requirements | | CTR-I001 | info | Consider adding performance metrics | | CTR-I002 | info | Consider documenting migration strategy | | CTR-I003 | info | Consider adding alternative approaches |

Validation Commands

# Validate single CTR document (validates both .md and .yaml)
python ai_dev_flow/scripts/validate_ctr.py docs/08_CTR/CTR-001_example.md

# Validate all CTR documents
python ai_dev_flow/scripts/validate_ctr.py docs/08_CTR/

# Check with verbose output
python ai_dev_flow/scripts/validate_ctr.py docs/08_CTR/ --verbose

Validation Workflow

  1. Parse YAML frontmatter
  2. Check required metadata fields
  3. Validate tag taxonomy
  4. Verify section structure (1-12)
  5. Validate Document Control table
  6. Check companion YAML schema file exists
  7. Validate YAML schema (OpenAPI 3.x or JSON Schema)
  8. Check Error Handling section (Error Codes table)
  9. Verify Provider/Consumer in Contract Definition
  10. Check Examples section (success and failure)
  11. Validate upstream references (7 required)
  12. Verify file naming convention
  13. Generate validation report

Integration

  • Invoked by: doc-flow, doc-ctr (post-creation)
  • Feeds into: trace-check (cross-document validation)
  • Reports to: quality-advisor

Output Format

CTR Validation Report
=====================
Document: CTR-001_example.md
Status: PASS/FAIL

Dual-File Check:
- Markdown file: Present
- YAML schema file: Present/Missing
- Schema valid: Yes/No

Contract Structure:
- Provider defined: Yes/No
- Consumer defined: Yes/No
- Error codes table: Present/Missing

Schema Coverage:
- OpenAPI/JSON Schema: Valid/Invalid
- Request schemas: Complete/Incomplete
- Response schemas: Complete/Incomplete
- Error responses: Defined/Missing

Errors: N
Warnings: N
Info: N

[Details listed by severity]

Related Resources

  • CTR Skill: .claude/skills/doc-ctr/SKILL.md
  • Naming Standards: .claude/skills/doc-naming/SKILL.md (ID and naming conventions)
  • CTR Validation Rules: ai_dev_ssd_flow/08_CTR/CTR_MVP_SCHEMA.yaml
  • CTR Schema: ai_dev_ssd_flow/08_CTR/CTR_SCHEMA.yaml

Version History

| Version | Date | Changes | Author | |---------|------|---------|--------| | 1.2 | 2026-02-11 | Nested Folder Rule: Added Section 0 Folder Structure Validation (BLOCKING); CTR must be in docs/08_CTR/CTR-NN_{slug}/ folders; Added error codes CTR-E020, CTR-E021, CTR-E022 | | 1.1.0 | 2026-02-08 | Updated layer assignment from 9 to 8 per LAYER_REGISTRY v1.6; removed @impl from cumulative tags | System | | 1.0.0 | 2025-01-15 | Initial validator skill definition | System |

Implementation Plan Consistency (IPLAN-004)

  • Treat plan-derived outputs as valid source mode and verify intent preservation from implementation plan scope/objectives.
  • Validate upstream autopilot precedence assumption: --iplan > --ref > --prompt.
  • Flag objective/scope conflicts between plan context and artifact output as blocking issues requiring clarification.
  • Do not introduce legacy fallback paths such as docs-v2.0/00_REF.