docs: add module and dataclass docstrings for contributors who want to understand the codebase

All 10 source modules now have module-level docstrings explaining their
purpose. The 5 key dataclasses (Check, CheckResult, Context, ContextResult,
Instruction) have docstrings documenting their fields and behavior.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 2 people

src/ralphify/__init__.py

@@ -1,3 +1,8 @@
+"""Ralphify — a minimal harness for running autonomous AI coding loops.
+
+Exposes the ``ralph`` CLI entry point and the package version.
+"""
+
 from importlib.metadata import PackageNotFoundError, version
 
 try:

src/ralphify/_frontmatter.py

@@ -1,3 +1,13 @@
+"""Parse YAML frontmatter from primitive markdown files and discover primitives.
+
+All three primitive types (checks, contexts, instructions) store their
+configuration in markdown files with ``---``-delimited frontmatter.
+This module provides the shared parsing and directory-scanning logic.
+
+HTML comments in the body are stripped so users can leave notes that
+don't leak into the assembled prompt.
+"""
+
 import re
 from collections.abc import Iterator
 from pathlib import Path

src/ralphify/_output.py

@@ -1,3 +1,9 @@
+"""Combine and truncate subprocess output for prompt injection.
+
+Output from checks and contexts is capped at :data:`MAX_OUTPUT_LEN`
+characters (5 000) to avoid blowing up the agent's context window.
+"""
+
 from __future__ import annotations
 
 MAX_OUTPUT_LEN = 5000

src/ralphify/_runner.py

@@ -1,3 +1,10 @@
+"""Execute shell commands and scripts with timeout and output capture.
+
+Used by checks and contexts to run their configured command or ``run.*``
+script.  All commands run with ``cwd`` set to the project root, regardless
+of where the primitive directory is located.
+"""
+
 from __future__ import annotations
 
 import shlex

src/ralphify/checks.py

@@ -1,3 +1,11 @@
+"""Discover and run validation checks after each loop iteration.
+
+Checks are scripts or commands in ``.ralph/checks/<name>/`` that validate
+the agent's work (tests, linters, type checkers).  When a check fails its
+output and failure instruction are formatted for injection into the next
+iteration's prompt, creating a self-healing feedback loop.
+"""
+
 import warnings
 from dataclasses import dataclass
 from pathlib import Path
@@ -9,6 +17,13 @@
 
 @dataclass
 class Check:
+    """A validation check discovered from ``.ralph/checks/<name>/CHECK.md``.
+
+    Either *command* or *script* must be set.  If both exist, *script* wins.
+    The *failure_instruction* (body text from CHECK.md) is appended to the
+    prompt when the check fails, guiding the agent toward a fix.
+    """
+
     name: str
     path: Path
     command: str | None
@@ -20,6 +35,12 @@ class Check:
 
 @dataclass
 class CheckResult:
+    """Outcome of running a single :class:`Check`.
+
+    *passed* is ``True`` when the command exits with code 0.
+    *exit_code* is ``-1`` when the check timed out.
+    """
+
     check: Check
     passed: bool
     exit_code: int

src/ralphify/cli.py

@@ -1,3 +1,10 @@
+"""CLI commands for ralphify — init, run, status, and scaffold new primitives.
+
+This is the main module.  The ``run`` command implements the core autonomous
+loop: read prompt, resolve contexts and instructions, pipe to the agent,
+run checks, and repeat.
+"""
+
 import shutil
 import subprocess
 import sys

src/ralphify/contexts.py

@@ -1,3 +1,10 @@
+"""Discover and run dynamic data contexts injected before each iteration.
+
+Contexts live in ``.ralph/contexts/<name>/`` and provide fresh data to the
+prompt each loop — for example recent git history or current test status.
+A context can run a command/script, provide static text, or both.
+"""
+
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -9,6 +16,13 @@
 
 @dataclass
 class Context:
+    """A dynamic data context discovered from ``.ralph/contexts/<name>/CONTEXT.md``.
+
+    A context may have a *command* or *script* (whose stdout is captured),
+    *static_content* (the body text from CONTEXT.md), or both.  When both
+    are present the static content appears first, followed by the command output.
+    """
+
     name: str
     path: Path
     command: str | None = None
@@ -20,6 +34,13 @@ class Context:
 
 @dataclass
 class ContextResult:
+    """Outcome of running a single :class:`Context`.
+
+    *output* contains the command's stdout (empty string for static-only
+    contexts).  *success* is ``True`` when the command exits with code 0
+    or when no command was configured.
+    """
+
     context: Context
     output: str
     success: bool

src/ralphify/detector.py

@@ -1,3 +1,10 @@
+"""Auto-detect project type from manifest files.
+
+Used during ``ralph init`` to report the detected language ecosystem.
+Checks for common manifest files (package.json, pyproject.toml, etc.)
+and returns a short label like "python" or "node".
+"""
+
 from pathlib import Path
 
 

src/ralphify/instructions.py

@@ -1,3 +1,11 @@
+"""Discover and resolve static instruction text injected into each prompt.
+
+Instructions are reusable rules in ``.ralph/instructions/<name>/`` that get
+injected into the prompt every iteration — for example coding standards or
+git conventions.  Unlike contexts, they have no command; their content is
+the body text of the INSTRUCTION.md file.
+"""
+
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -7,6 +15,12 @@
 
 @dataclass
 class Instruction:
+    """A static instruction discovered from ``.ralph/instructions/<name>/INSTRUCTION.md``.
+
+    The *content* is the body text below the frontmatter.  Instructions with
+    empty content are silently excluded from prompt injection even if enabled.
+    """
+
     name: str
     path: Path
     enabled: bool = True

src/ralphify/resolver.py

@@ -1,3 +1,12 @@
+"""Template placeholder resolution shared by contexts and instructions.
+
+Handles three placement strategies:
+
+1. **Named** — ``{{ kind.name }}`` inserts a specific primitive's content.
+2. **Bulk** — ``{{ kind }}`` inserts all remaining primitives (alphabetically).
+3. **Implicit** — when no placeholders exist, all content is appended to the end.
+"""
+
 import re