Skip to main content

CODITECT Integration Guide

This guide explains how to integrate the CODITECT Document Management System with Claude Code for automatic frontmatter management.

Overview​

The integration provides:

  1. Automatic Frontmatter Injection - New documents get frontmatter automatically
  2. Timestamp Updates - Modified documents have their updated field refreshed
  3. Pre-commit Validation - Staged files are validated before commit
  4. CLI Tools - Command-line interface for document management

Quick Start​

1. Install Dependencies​

cd submodules/ops/coditect-document-management
pip install pyyaml

2. Configure Claude Code Hooks​

Add to your .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": {"tool_name": "Write"},
        "hooks": [{
          "type": "command",
          "command": "python3 scripts/coditect_integration/document_hooks.py --pre",
          "timeout": 10000
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": {"tool_name": "Write"},
        "hooks": [{
          "type": "command",
          "command": "python3 scripts/coditect_integration/document_hooks.py --post",
          "timeout": 10000
        }]
      }
    ]
  }
}

3. Set Up Pre-commit Hook​

# Option 1: Direct installation
cp scripts/coditect_integration/pre_commit.py .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

# Option 2: Use pre-commit framework
# Add to .pre-commit-config.yaml:
repos:
  - repo: local
    hooks:
      - id: frontmatter-validation
        name: Frontmatter Validation
        entry: python3 scripts/coditect_integration/pre_commit.py
        language: python
        types: [markdown]

CLI Commands​

Initialize Documents​

# Create new document with frontmatter
python -m coditect_integration.cli_wrapper init docs/new-guide.md --create

# Inject frontmatter into existing files
python -m coditect_integration.cli_wrapper init docs/ --dry-run
python -m coditect_integration.cli_wrapper init docs/

Validate Documents​

# Validate single file
python -m coditect_integration.cli_wrapper validate docs/README.md

# Validate directory
python -m coditect_integration.cli_wrapper validate docs/ -v

Update Timestamps​

# Update single file
python -m coditect_integration.cli_wrapper update docs/README.md

# Update all documents
python -m coditect_integration.cli_wrapper update docs/

Generate Coverage Report​

# Console output
python -m coditect_integration.cli_wrapper report docs/

# Save to file
python -m coditect_integration.cli_wrapper report docs/ -o coverage.md --json coverage.json

Quick Health Check​

# Check all standard directories
python -m coditect_integration.cli_wrapper check -v

Hook Events​

PreToolUse: Document Creation​

When Claude Code creates a new markdown file via the Write tool:

  1. Hook receives file path and content
  2. Checks if file matches document patterns (docs/, agents/, etc.)
  3. If no frontmatter exists, generates and injects it
  4. Returns modified content to Claude Code

Auto-detected fields:

  • title - Extracted from first H1 heading or filename
  • type - Inferred from file path (guide, adr, reference, etc.)
  • created / updated - Current date
  • version - "1.0.0"
  • status - "draft"

PostToolUse: Document Modification​

When Claude Code modifies an existing markdown file:

  1. Hook receives file path after modification
  2. Reads current content and parses frontmatter
  3. Updates updated field to current date if changed
  4. Writes back updated content

Document Patterns​

Files in these paths receive automatic frontmatter:

Path PatternDocument Type
docs/**/*.mdreference
agents/*.mdagent
commands/*.mdcommand
skills/*/SKILL.mdskill
workflows/*.mdworkflow
guides/*.mdguide
adrs/*.mdadr
architecture/*.mdarchitecture

Excluded paths:

  • node_modules/
  • .git/
  • __pycache__/
  • .venv/
  • .backups/
  • LICENSE.md
  • CHANGELOG.md

Frontmatter Schema​

Standard frontmatter fields:

---
title: "Document Title"           # Required
type: guide                       # Required: guide, adr, reference, etc.
version: "1.0.0"                  # Required: semantic version
created: "2025-12-28"             # Required: ISO date
updated: "2025-12-28"             # Required: ISO date
status: draft                     # Required: draft, review, approved, deprecated
tags:                             # Optional: list of keywords
  - integration
  - hooks
summary: "Brief description"      # Optional: 1-2 sentence summary
---

Troubleshooting​

Hook Not Running​

  1. Check .claude/settings.json syntax
  2. Verify Python is in PATH: which python3
  3. Test hook manually: 
    echo '{"tool_name":"Write","tool_input":{"file_path":"test.md","content":"# Test"}}' | \
      python3 scripts/coditect_integration/document_hooks.py --pre

Pre-commit Fails​

  1. Run validation manually: python3 scripts/coditect_integration/pre_commit.py -v
  2. Check for missing frontmatter: python -m coditect_integration.cli_wrapper check -v
  3. Inject missing frontmatter: python -m coditect_integration.cli_wrapper init docs/

Import Errors​

Ensure you're running from the correct directory:

cd submodules/ops/coditect-document-management
python -m coditect_integration.cli_wrapper --help

Architecture​

scripts/coditect_integration/
├── __init__.py          # Package exports
├── document_hooks.py    # Claude Code PreToolUse/PostToolUse handlers
├── pre_commit.py        # Git pre-commit validation
├── cli_wrapper.py       # Unified CLI (init, validate, update, report)
└── hooks-config.json    # Sample hooks configuration

scripts/frontmatter_toolkit/
├── parser.py            # YAML frontmatter extraction
├── validator.py         # Schema validation
├── injector.py          # Frontmatter injection
├── updater.py           # Timestamp updates
└── cli.py               # Standalone CLI

See Also​