Skip to main content

Post-ADR Create Hook

Purpose​

Automatically updates ADR indexes, cross-references, and related documentation after a new ADR is created.

Trigger​

Fires automatically after /adr-decision command completes successfully.

Actions​

1. Update ADR Index​

def update_adr_index(adr_path: str, adr_metadata: dict) -> None:
    """Add new ADR to the category index."""
    index_path = os.path.dirname(adr_path) + '/INDEX.md'

    entry = f"""
| [{adr_metadata['number']}]({adr_metadata['filename']}) | {adr_metadata['title']} | {adr_metadata['status']} | {adr_metadata['date']} |
"""

    # Append to index table
    with open(index_path, 'a') as f:
        f.write(entry)

2. Update Master ADR List​

def update_master_list(adr_metadata: dict) -> None:
    """Update the master ADR list in architecture docs."""
    master_path = 'internal/architecture/ADR-INDEX.md'

    entry = {
        'number': adr_metadata['number'],
        'title': adr_metadata['title'],
        'category': adr_metadata['category'],
        'status': adr_metadata['status'],
        'path': adr_metadata['path']
    }

    # Add to master list
    # ... implementation

3. Add Cross-References​

def add_cross_references(adr_path: str, related_adrs: list) -> None:
    """Add links to related ADRs in both directions."""
    for related in related_adrs:
        # Add reference from new ADR to related
        append_reference(adr_path, related)

        # Add reference from related ADR to new
        append_reference(related, adr_path)

4. Update Context Database​

def record_decision(adr_metadata: dict) -> None:
    """Record the decision in org.db (ADR-118 Tier 2: IRREPLACEABLE)."""
    import sqlite3
    from scripts.core.paths import get_org_db_path

    conn = sqlite3.connect(get_org_db_path())  # ADR-118: decisions in org.db
    conn.execute("""
        INSERT INTO decisions (decision, rationale, source, created_at)
        VALUES (?, ?, ?, datetime('now'))
    """, (
        adr_metadata['title'],
        adr_metadata['justification'],
        adr_metadata['path']
    ))
    conn.commit()
    conn.close()

5. Archive Research Artifacts​

def archive_research(topic: str, artifacts: dict) -> None:
    """Archive research artifacts for future reference."""
    import json
    from datetime import datetime

    archive_dir = f"context-storage/adr-research/{topic.replace(' ', '-')}"
    os.makedirs(archive_dir, exist_ok=True)

    for name, data in artifacts.items():
        path = f"{archive_dir}/{name}"
        with open(path, 'w') as f:
            json.dump(data, f, indent=2)

6. Generate Notification​

def notify_stakeholders(adr_metadata: dict) -> None:
    """Generate notification for relevant stakeholders."""
    notification = {
        'type': 'adr_created',
        'title': f"New ADR: {adr_metadata['title']}",
        'summary': adr_metadata['summary'],
        'path': adr_metadata['path'],
        'decision': adr_metadata['chosen_option'],
        'category': adr_metadata['category']
    }

    # Write to notifications queue
    # ... implementation

Hook Output​

{
  "success": true,
  "actions_completed": [
    "Updated category index",
    "Updated master ADR list",
    "Added 3 cross-references",
    "Recorded decision in context DB",
    "Archived 5 research artifacts"
  ],
  "artifacts": {
    "adr_path": "internal/architecture/adrs/cloud-platform/ADR-015-multi-machine-sync.md",
    "research_archive": "context-storage/adr-research/multi-machine-sync/",
    "cross_references": ["ADR-003", "ADR-007", "ADR-012"]
  }
}

Configuration​

# In .coditect/hooks.yaml
post-adr-create:
  enabled: true
  update_index: true
  add_cross_references: true
  record_in_db: true
  archive_research: true
  notify: false  # Disabled by default

Integration​

Called automatically after successful /adr-decision completion.

# In adr-decision command completion
if adr_created_successfully:
    hook_result = run_hook('post-adr-create', {
        'adr_path': created_adr_path,
        'adr_metadata': adr_metadata,
        'research_artifacts': research_data,
        'related_adrs': identified_related_adrs
    })

    print("\nPost-creation actions:")
    for action in hook_result['actions_completed']:
        print(f"  ✓ {action}")

Last Updated: 2025-12-29