Modular rules, skills, and workflows to configure and constrain AI coding assistants.
See the Getting Started Guide to integrate Predicate into your project.
predicate/
├── rules.md # The master ruleset: the Verification Dual and the Prime Invariants every walker inherits
├── ambient.md # Always-on principles that are not workflows (no entrypoint)
├── skills/ # Encapsulated agent skills (rules, workflows, tools)
├── ledger/ # Nickel contracts that make campaign artifacts machine-valid
├── gates/ # Standalone evaluator scripts (orphan, self-containment)
├── hooks/ # Git hooks that enforce the Commit Gate at commit time
├── templates/ # Project templates (IBC.md, ADR.md, etc.)
└── docs/ # Guides, the orchestration protocol, ADRs, and theory
Two directories are runtime-only and gitignored by the parent repository: .scratch/
holds a campaign's ephemeral working set, and .ledger/ is the durable history
sub-repository (the flight recorder). Neither is tracked here; see
the flight recorder below.
Predicate packages all agent assets as skills:
| Term | Category | Description |
|---|---|---|
| Rule | Constraint | Declarative guardrails (like rust or engineering guidelines). |
| Workflow | Procedure | State-machine SOPs (like core, refine, or campaign). |
| Tool | Capability | Executable scripts (like security-audit). |
Prompt engineering is a fragile way to program. Autoregressive language models do not "think" or "reason"; they execute a stochastic walk across a discrete token state-space. Over long generations, errors compound. Without external constraints, an agent will eventually drift off course, write unverified code, or introduce regressions.
Predicate's core invariant is the Verification Dual: verify, then trust. No condition is ever closed by an agent's say-so. Every condition that must hold is closed by the strongest applicable evaluator, and exactly one of two complementary paths closes it:
- The symbolic path. If a deterministic evaluator exists or can be built — a proof, a type, a property test, an example test, a linter — it must be used. The evaluator's exit code is the verdict; the agent's self-report is ignored. The hierarchy, strongest first:
proof > type > property test > example test > linter. - The adversarial path. If no deterministic evaluator can exist, the condition is closed by adversarial review from context-free agents operating out of decorrelated boundaries. Decorrelation is load-bearing: a single reviewer shares the generator's attractor basin, so their blind spots coincide; context-free reviewers in different basins have non-overlapping blind spots whose union covers the artifact.
Both paths iterate to a fixed point against error feedback toward
The full ruleset lives in rules.md: six Prime Invariants in precedence order, the ambient boundary condition every walker inherits. The Dual is the first; the others are Halt over assumption (ambiguity freezes the walk — guessing is forbidden), The Cutting Imperative (below), The history is the deliverable (git log is the durable interface to human judgment), Track state; reconstruct, don't recall, and Tier economy (route every task to the cheapest walker whose capability bounds it).
Unjustified code, stale docs, and redundant skills are excess phase-space volume — drift surface. "Cut complexity" is the same invariant as "narrow the basin," applied to artifacts rather than tokens. A standing maturity flag sets the default stance:
molten(pre-1.0) flips the default from "amend only" to refactor and cut freely.stable(post-1.0) restores amend-by-default, with cuts justified per change.
This project's default is molten. Treating a work-in-progress, mostly-machine-authored repository as a human-vetted immutable structure to be amended only is a defect, not caution.
A skill is an authority you invoke for a moment (/core, /campaign, /refine). Beneath the skills sits the ambient layer — standing principles that are never not active and so have no entrypoint to route to. They live in ambient.md, presumed read alongside rules.md, and bind every walk whether or not a skill is invoked. When an ambient principle and an invoked skill speak to the same situation, the skill is the procedural authority for how; the ambient principle states the standing constraint on whether and why.
The ambient layer holds:
- Planning invariants — the Candor Obligation (challenge flawed premises directly; no hedging), Sketch Commit Discipline (every touch a commit), and Strategic Escalation (drift that violates an IBC's goal or non-goals halts the walk).
- The sketch principle — explore before you propose; alternatives are required; draft thinking stays draft. Exploration is a standing disposition, not a discrete step.
- The dialectic principle — thesis ⇄ adversarial antithesis → synthesis is the shape of the system. Its high-stakes tier switches the generating model itself, the strongest form of the Dual's decorrelation.
- Boundary reconstruction — drift is the default of open-loop generation, so a long walk periodically rebuilds its boundary from the durable sources rather than trusting accumulated context.
- The Outward-Search Reflex — before halting on a missing fact or pattern, run a bounded outward search (prior art, RFCs, literature); halting with a question you could have answered by looking is the same defect class as guessing.
- Code-edit constraints — mandatory halt conditions, production-grade correctness rules, and the robust-testing mandate, binding whenever code is written.
Several of these were historically packaged as invokable skills only because past harnesses had no other place to put them; they belong in the substrate, not behind an entrypoint.
Predicate's coordination spine runs from contract to orchestration. Below it sit the single-walk execution workflows; above it sit the two tier-aware workflows that govern work across heterogeneous model classes.
The single-walk workflows separate concerns rather than phases of one pipeline — you use only what you need. Each is invoked by moment, runs as a strict state machine, and closes at the Commit Gate:
| Workflow | Focus | Entrypoint | Essence |
|---|---|---|---|
| Formalize a domain | Build or apply a mathematical model | /form |
Select the simplest math that captures the domain; halt for approval before building. |
| Execute plan steps | Drive granular changes to commit | /core |
TDD state machine (Absorb → Clarify → Plan → Execute) with review blocks at each boundary. |
| Optimize existing artifacts | Audit and polish in place | /refine |
Contraction loop with multi-sweep adversarial review until findings reach zero. |
| Write or audit documentation | Structured documentation lifecycle | /doc |
Audit → Plan → Draft → Review → Verify against the Divio quadrants. |
| Maintain project history | Incremental chronicle updates | /chronicle |
Summarize commit batches between SHA cutoffs into docs/chronicle.md. |
A well-scoped change goes straight to /core; /form can be invoked anywhere to formalize domain boundaries; /refine optimizes existing artifacts. Exploring before committing is the always-on ambient sketch principle, not a workflow.
The spine itself is the two tier-aware workflows:
/boundarymanufactures and adversarially refines the prompt contract (the Initial Boundary Condition, or IBC) before any expensive or autonomous walk launches. Seven sufficiency conditions (S1–S7) govern every IBC — falsifiable premises, a first-class rejection genre, resolved/delegated/reserved decision rights, evaluator attachment, curated context, load-bearing vs plastic amendment rights, and boundary mass scaled to walker capability. A good boundary is optimized for cheap rejection: the receiving model must be able to refute a wrong frame in its first few hundred tokens. No expensive walk runs without a sufficient, human-approved boundary./campaignlets an architect-class model frame the initiative, survey exhaustively, derive a mitigation plan as a dependency graph of worker tasks, emit one IBC per task routed to the cheapest capable tier, and judge the work that returns. Strategic framing and stress-test planning — what a standalone charter or plan once held — are produced and consumed inside/campaign's ABSORB, SURVEY, and PLAN states in one architect pass. After each dispatch it reconciles: re-running evaluators on landed work and re-verifying every pending prompt's premises against currentHEADbefore dispatching further.
The what of the execution layer is prose in the campaign skill; the how is specified deterministically in the machine-executable orchestration protocol — the exact procedure that drives a validated campaign DAG to a correctly merged branch, running identically whether a human, an agent, or an external tool drives it. Everything in it is deterministic-or-dispatched except a small set of explicitly marked [HUMAN SEAM] points (final acceptance and push, non-resolvable reserved halts, decision-rights realignment, and non-converging adversarial review).
The Verification Dual's symbolic path is not a convention an agent is asked to remember — it is machinery. Three layers make it intrinsic:
- The Nickel ledger (ledger/). Every state artifact a campaign produces — its boundary, its DAG, its findings, its reconciliation record — is a Nickel contract. The contracts make the artifacts' invariants intrinsic: a malformed artifact cannot be exported. The DAG contract enforces acyclicity, referential integrity, and that concurrent nodes declare disjoint file surfaces; the findings and reconcile-log contracts enforce one principle — a condition is only closed once the evaluator that closes it is named.
- The gates (gates/). Standalone evaluator scripts that close conditions a generic doc check cannot:
check_orphans.shis the referential-truth gate (a reference that names a removed or demoted workflow as if it were live fails it), andcheck_selfcontained.shrejects commit messages with references a stranger readinggit logcould not resolve. - The git hooks (hooks/).
hooks/install-hooks.shwires acommit-msghook (Conventional Commits form plus self-containment) and apre-commithook (staged markdown links valid, staged Nickel artifact satisfies its contract, no staged file references a removed workflow as live). The installer is worktree-aware, so one install covers the main checkout and every linked worktree. A violation blocks the commit — the Commit Gate enforced as a gate, not a memory.
The Commit Gate runs in every repository, including the independent .ledger/ sub-repository and every worktree. The message must pass the commit-hygiene validator. The staged surface is then checked in two layers with different activation (see rules.md §3): the structural layer always runs — staged markdown links must be valid, staged Nickel artifacts must satisfy their contracts, and no staged file may orphan a removed workflow; the authority layer runs only when a campaign is in flight, signalled by the .ledger/active-dag pointer — when that pointer is present, every staged path must fall under some campaign node's declared file_surface. An ordinary commit with no pointer gets the structural layer alone. The full test suite and linters must also run.
Exploration before commitment is the always-on sketch principle (an ambient layer principle, above). Its durable substrate is the flight recorder at .ledger/log/. The principle and the substrate are distinct: the disposition is ambient, the recorder is load-bearing infrastructure.
The topology has two runtime directories, both gitignored by the parent repository so it never tracks transient or subrepo state:
.scratch/— a campaign's ephemeral working set (live review, plan, orchestration, and prompts). Mutable and never committed..ledger/— an independent sub-repository with its own git history. Its.ledger/log/subtree is the flight recorder: a committed, linear record of every architectural decision, discovery, and pivot, checkpointed at each reconciliation boundary. Because the parent ignores.ledger/but the subrepo commits internally, the record is durable within the subrepo without polluting the parent's history — and any campaign can be regenerated from the recorder plusgit.
Every modification is committed to the flight recorder immediately (Sketch Commit Discipline). This creates a linear history that lets any walk reconstruct full context from a single subtree. It serves as a living record across all workflows: domain maps under /form, execution notes under /core, sweep traces under /refine, sufficiency objections under /boundary, and reconcile checkpoints under /campaign.
The Dual rests on a control-theoretic model of generation. The math is still the foundation; it is the substrate beneath the doctrine, not the headline.
-
Stochastic walks: Token generation is a walk across a transition graph:
$P(\mathbf{S}_{t+1} \mid \mathbf{S}_t)$ , where the prefix sequence$\mathbf{S}_t$ defines the state at step$t$ . -
Entropy control: Token selection uses the Gibbs-Boltzmann distribution:
$$P(x_i) = \frac{\exp(z_i / \tau)}{\sum_j \exp(z_j / \tau)}$$ where$z_i$ represents the logits and$\tau$ is thermodynamic temperature. Lowering temperature collapses entropy, forcing deterministic local optimization. -
Closed-loop feedback: An open-loop agent will eventually drift. Predicate closes the loop by running external, deterministic validators (compilers, linters, test runners). It captures the validator's output as an error differential (
$\Delta E$ ) and injects corrective prompt feedback ($\Delta \mathbf{S}_{k+1}$ ) to drive the system toward a zero-error state:$$\mathbf{S}_{k+1} = \mathbf{S}_k \oplus \Delta \mathbf{S}_{k+1}$$
Predicate models the agent's prompt as an Initial Boundary Condition (IBC) that warps this probability landscape, carving a deep attractor basin to guide token selection. The Dual is the discipline that keeps the walk inside that basin: the symbolic path is the closed feedback loop made deterministic, and the adversarial path is the same loop run by decorrelated reviewers where no deterministic loop can exist.
The formalism also covers the prevention half — three phenomena the doctrine acts on but the four core mappings leave implicit:
-
Attention-dilution: the IBC's attractor hold decays as context grows (
$I(\mathbf{c}_0; x_t)$ is non-increasing in$t$ ), which is why the boundary-reconstruction reflex re-injects the highest-precedence invariants at each long-horizon step rather than trusting accumulated context. -
Design-space constriction: the same phase-space-contraction operator that prunes valid trajectories per token also prunes valid designs per discovered constraint. The
molten/stablematurity flag tracks the rate of that contraction — high rate means the basin is still moving; rate approaching zero means it has settled. -
Basin-nesting: goals are nested basins (
$B_{\text{task}} \subset B_{\text{component}} \subset B_{\text{project}} \subset \cdots$ ); a move can satisfy the innermost constraint while exiting a parent basin — the formal definition of a defeater and the trigger for Strategic Escalation.
The full first-principles derivation — the Markov-chain assumption, the Boltzmann engine, phase-space constriction, closed-loop control, and the prevention-half extension — lives in docs/theory/formalism.md.
See the Getting Started Guide for setup instructions.
Predicate is designed to be forked and customized. You can easily add organization-specific rules, workflows, or custom validators. See docs/authoring.md to write your own skills.
MIT