Directory Predicates — Enforceable Software Engineering Conventions

Why dirp

Main Features

🗣️

Standard Concretization

A shared vocabulary for efficient communication between humans and agents. Express complex engineering requirements as compact, unambiguous DP identifiers.

1 Write project prompts with DP IDs: "I want a repo that satisfies DP-10217, DP-10479"
2 Release plugin standards with predicates: "All submissions must satisfy DP-12176"

📐

Convention Enforcement

Give coding agents a machine-checkable specification. Run dp-checker at the end of each loop iteration for verifiable, actionable guarantees on deliverables.

1 In your agent loop, always run dp-checker at the end
2 On failure, feed the error message back to the agent to iterate and fix

🔍

Repository Analysis

Understand any repository's characteristics without reading every file. Lite predicates run in milliseconds and produce a structured, token-efficient summary.

1 Run all lite predicates on a new repo
2 Instantly know: "This is a React TS repo with Docker" — satisfies DP-299, DP-43 — without wasting tokens

Anatomy

Predicate Example

Hover over a field on the left to highlight the corresponding part in the implementation, and vice versa.

Predicate Fields

id

Unique integer ID, starting from 1000 (0–999 reserved). Required.

name

A function-name identifier that explains the predicate's meaning in a straightforward way.

description

Detailed description including what it checks, why it's important, and relevant context or examples.

code

The implementation — a function returning DpResult (Result<DpOutcome, String>). Use .into() to convert booleans or tuples.

after optional

List of dp_ids that must run before this predicate — declares dependencies.

lite optional

Default false. If true, included in the fast lite check. Must run within 10ms, with no external dependencies or side effects.

deprecated optional

Default None. ID of the replacement predicate (marks this one as deprecated).

Implementation

use dirp_macro::dp;
use crate::{DpContext, DpResult};
use std::collections::HashMap;
#[dp(id = 10000, after = [1000], lite = false)]
/// A Rust workspace
fn rust_workspace(ctx: &DpContext, prior: &HashMap<u32, DpResult>) -> DpResult {
    match prior.get(&1000) {
        Some(Ok(outcome)) if !outcome.verdict =>
            return Ok((false, "no Cargo.toml").into()),
        Some(Err(e)) => return Err(format!("dependency dp-1000 failed: {e}")),
        _ => {}
    }
    // ...
    Ok(true.into())
}

Get Started

Quick Start

Install dirp with a single command, then integrate it into your workflow.

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/dirp-dev/install/HEAD/install.sh)"

Manually run DP checks on any repository to verify it meets specific conventions. Useful for CI pipelines, pre-merge checks, and reviewing third-party code.

dirp check [dp_id ...]

Runs the specified predicates against the current directory by default. Pass one or more DP IDs to check specific conventions. Exit code is non-zero if any predicate fails, making it easy to integrate into scripts and CI.

Flag	Description
--path <dir>	Run against a specific directory instead of the current working directory.
--verbose	Show detailed output for each predicate, including pass/fail reasons and execution time.
--json	Output results as JSON for programmatic consumption.
--all	Run all registered predicates (including non-lite ones) instead of a specified subset.

Integrate DP checks directly into your coding agent loop for automated quality enforcement. The agent runs, dirp checks the output, and the error message feeds back in — until the repo satisfies all predicates.

dirp can run as a Claude Code Stop hook to automatically check predicates when Claude finishes responding. If any predicates fail, Claude is blocked from stopping and receives feedback to fix the issues.

Add the following to your .claude/settings.json (project-level) or ~/.claude/settings.json (user-level):

{ "hooks": { "Stop": [ { "matcher": "", "hooks": [ { "type": "command", "command": "dirp cc-hook dp-1000 dp-1001 dp-1002" } ] } ] } }

Replace the predicate IDs with the ones you want to enforce. When any of the specified predicates fail, Claude will see a message like:

The following directory predicates failed: - dp-1000 (has_cargo_toml): FAIL Description: Directory contains a Cargo.toml file, indicating a Rust project 0/1 predicates passed. Please fix the failing predicates before finishing.

Quickly understand a repository's characteristics without reading every file. dirp analyze runs all lite predicates and returns a structured summary — perfect for orienting a new agent or getting a token-efficient overview.

dirp analyze

Runs the full set of lite predicates and outputs a structured report of which conventions the repository satisfies. Each lite predicate is guaranteed to complete in under 10ms with no side effects.

Sample output

Repository: ./my_blog Analyzed: 47 lite predicates in 312ms ✓ DP-43 use_typescript TypeScript project detected (tsconfig.json found) ✓ DP-299 has_dockerfile Dockerfile found at project root ✓ DP-10011 uv_python_project uv-managed Python project (pyproject.toml + .venv) ✗ DP-10055 detect_secrets Potential secret found: secret.py contains hardcoded key ✓ DP-10217 pnpm_workspace pnpm workspace configuration detected ··· Result: 44/47 passed · 3 failed

Flag	Description
--path <dir>	Analyze a specific directory instead of the current working directory.
--verbose	Show full predicate descriptions alongside results.
--json	Output results as structured JSON for piping into other tools or agents.
--failed-only	Only show predicates that failed, for a focused action list.