Skip to content

Contributing to the AI Hub

What it is

The CONTRIBUTING.md guide is the primary governance document defining how humans and AI agents (e.g., Claude 5.6, GPT-5.6, Gemini 4.0 Pro/Ultra, DeepSeek-V4, Llama 4, Gemma 3, and Qwen 3.8) collaborate to maintain the Home-Office Automation & AI Hub. It serves as the operational manual for the repository's "KnowledgeOps" framework in early January 2027.

What problem it solves

It prevents "documentation rot" and repository fragmentation by enforcing a unified taxonomy, deduplication protocols, and the Ralph-loop automation cycle. It ensures that every contribution—whether a tool update or a new architectural pattern—meets the "High Confidence" early January 2027 State-of-the-Art standard.

Where it fits in the stack

Governance Layer — It sits alongside AGENTS.md and standards.md as the foundational contract for all repository activities, providing the "rules of engagement" for autonomous agents and human developers.

Typical use cases

  • Agent Onboarding: Establishing the "Quick Start" sequence for new LLM agents.
  • Ralph-loop Execution: Defining how Jules (the primary agent) processes, decomposes, and closes issues.
  • Quality Assurance: Providing the checklist for AI-authored PRs.
  • Catalog Maintenance: Standardizing the ingestion of new sources via docs/new-sources/.

Strengths

  • Agent-First Design: Optimized for ingestion and execution by frontier models like Claude 5.6, GPT-5.6, and DeepSeek-V4.
  • Systematic Decomposition: The Ralph-loop (Action C) allows complex technical debt to be broken into manageable batches with extracted context and sub-task logs.
  • Multi-Agent Ready: Supports a Federated KnowledgeOps model using FastMCP 3.1 for high-performance tool execution and cross-agent orchestration.

Limitations

  • High Friction for Humans: The strict metadata and 13-section "High Confidence" requirements can be demanding for manual contributors.
  • Script Dependency: Relies heavily on the scripts/ directory for validation (e.g., audit_docs_quality.py).

When to use it

  • Before opening a Pull Request or Issue in the AI Hub.
  • When configuring a new AI agent or automation lane to work on this repository.
  • During "Maintenance Runs" to verify documentation compliance and technical freshness.

When not to use it

  • For ephemeral personal notes, local-only research, or draft configurations that will not be committed to the main hub.

Getting started

How You Can Help

We welcome contributions from both humans and AI agents: - Add New Tools: Found a tool that fits the stack? Document it using our templates. - Refine Playbooks: Improve our existing automation guides with more technical detail or new variants. - Update Services: Ensure the documentation for self-hosted services remains accurate as versions change. - Improve Prompts: Optimize our LLM prompt templates for better extraction and classification results.

LLM Agent Quick Start

Before changing files, agents must read these in order: 1. AGENTS.md — Repository operating contract, checklists, and quality bar. 2. skills.md — Reusable task patterns for intake, docs updates, and branch hygiene. 3. Standards — Taxonomy, metadata rules, and canonical-page requirements.

The Ralph-loop Protocol

This repository implements the Ralph-loop, a systematic directive for AI agents (primarily Google Jules) to close issues by performing one of three actions: - Action A (Do the work): Implement features or perform technical freshness audits (e.g., early January 2027 SOTA updates). - Action B (Add links): Find the appropriate canonical location for provided external links. - Action C (Decompose): Divide complex tasks into smaller, trackable issues with extracted context (see docs/reports/).

Assigning a Task to Jules

You can request Jules to perform a task by: 1. Opening an Issue: Describe the task clearly (e.g., "Add documentation for Tool X"). 2. Adding the Label: Apply the label jules (case-insensitive) to the issue. 3. Review the Plan: Jules will analyze the task and post a plan as a comment. Once you approve, Jules will get to work.

AI PR Checklist

Before requesting review, AI-authored PRs must satisfy: - [ ] Canonical page search completed (name + aliases). - [ ] No duplicate canonical pages introduced. - [ ] Correct 13-section "High Confidence" template and taxonomy used. - [ ] Required metadata added (Last reviewed, Confidence, Sources / References). - [ ] At least one high-signal source URL included. - [ ] data/all_tools.json and mkdocs.yml updated when applicable. - [ ] scripts/audit_docs_quality.py and scripts/check_docs_contract.py pass with 100% compliance.

CLI examples

Verify contribution quality and identify tasks using the repository's internal toolset:

# Run full technical freshness audit across the repository
python3 scripts/audit_docs_quality.py

# Verify KnowledgeOps contract for a specific file
python3 scripts/check_docs_contract.py docs/services/n8n.md

# Find oldest issues for Ralph-loop processing
python3 scripts/find_oldest_issues.py

# Update growth metrics and track category health
python3 scripts/growth_tracker.py

API examples

Programmatic Contribution Metadata Validation with Pydantic v2 (Python)

An automated validator using modern Pydantic v2 syntax to enforce Contribution Metadata compliance.

import sys
from datetime import date
from typing import Literal
from pydantic import BaseModel, Field, field_validator

class ContributionMetadata(BaseModel):
    last_reviewed: date = Field(..., description="The date of last review (YYYY-MM-DD)", alias="Last reviewed")
    confidence: Literal["high", "medium", "low"] = Field(..., description="Audit confidence level", alias="Confidence")

    @field_validator("last_reviewed")
    @classmethod
    def validate_recent_date(cls, v: date) -> date:
        if v < date(2027, 1, 1):
            raise ValueError("Review date must be within calendar year 2027 or later")
        return v

# Simulated ingestion pipeline
def check_compliance(metadata_dict: dict) -> bool:
    try:
        validated = ContributionMetadata.model_validate(metadata_dict)
        print("Metadata is compliant:", validated.model_dump(by_alias=True))
        return True
    except Exception as e:
        print("Non-compliant metadata:", e, file=sys.stderr)
        return False

# Usage
test_meta = {"Last reviewed": "2027-01-07", "Confidence": "high"}
check_compliance(test_meta)

Programmatic Integration with FastMCP 3.1 Task Protocol

Under FastMCP 3.1, a verification tool standardizes reports using the Task Protocol schemas.

import json
import urllib.request

def submit_standards_verification(task_id: str, file_path: str, passed: bool):
    url = "http://localhost:8000/tasks/v1/verify"
    payload = {
        "task_id": task_id,
        "step_name": f"standards-verification-{file_path}",
        "status": "passed" if passed else "failed",
        "metadata": {
            "standards_version": "2027.01",
            "enforcing_model": "Claude 5.6"
        }
    }

    req = urllib.request.Request(
        url,
        data=json.dumps(payload).encode('utf-8'),
        headers={'Content-Type': 'application/json'},
        method='POST'
    )

    with urllib.request.urlopen(req) as response:
        return json.loads(response.read().decode())

Sources / references

Contribution Metadata

  • Last reviewed: 2027-01-07
  • Confidence: high