Yakherd

Yakherd - herds the yaks so your agent stops shaving them.

Yakherd installs a strict, repository-centered single source of truth (SSOT) harness for agentic software projects. It gives Architecture, Implementation, Red Team, Temporary Branch, and Governor tasks durable ownership rules before the first product prompt arrives.

Absolute Beginner? Start Here

You do not need to understand "SSOT," Git, Python, or software architecture to start. Yakherd is the project-management and reliability half of vibe coding. It gives a coding agent a disciplined way to plan, build, check, and remember a software project without letting important decisions disappear into old chats.

You provide the other half: your idea, usually written as a master prompt. The master prompt describes what you want the software to do. Yakherd does not invent that idea for you; it gives the agent a safer, more organized working environment in which to build it.

In short:

1. Yakherd provides the operating system for the work: roles, plans, decisions, evidence, review, and a durable source of truth.
2. Your master prompt provides the product: the problem, users, desired behavior, constraints, and definition of success.
3. An agentic coding environment uses both to build the software.

Yakherd installs a START_HERE.md handoff for Codex. One explicit launch message asks Codex to create all five inspectable role-agent threads under a non-authoritative coordinator. Red Team runs the bootstrap gate immediately; Architecture waits for the master prompt; Implementation and Temporary Branch park; and Governor remains inactive until separately approved. This gives the user a visible team without violating the single-writer rule.

After that one-time integrity check, governance is proportional. Reversible bounded work goes directly from a brief you confirm to Implementation. Strict Architecture and Red Team gates are reserved for the concrete high-consequence slice being attempted—not imagined future features—and stop after at most two failed reviews.

The coding environment must be able to read and write project files, run shell commands, use Git, and run Python 3.11 or newer. Codex or Claude Code can do this when its execution environment also has Git and Python 3.11 or newer. An ordinary AI web chat without filesystem and shell tools cannot install Yakherd merely from a URL.

Which Coding Agents Work?

The governance files and role prompts are product- and model-neutral. AGENTS.md is the authority, while CLAUDE.md is only an import adapter; they do not create two competing copies of the rules. Agent instruction files are behavioral context, not a security sandbox, and the client must actually load them before work begins.

Tell Your Agent To Install It

If all you know how to do is talk to your coding agent, that is enough. Use the prompt for your environment.

Codex:

Install or upgrade Yakherd with pip, inspect the actual project folder, and run yakherd setup there. Do not infer retrofit merely because the folder exists. Setup must preserve unrelated files and stop on any Yakherd-path collision. Run yakherd doctor, then tell me to open the folder as my Codex project and say Start Yakherd.

Claude Code:

Install or upgrade Yakherd with pip, inspect the actual project folder, and run yakherd setup there. Preserve unrelated files and stop on any Yakherd-path collision. Run yakherd doctor, then open the repository as the Claude Code project and start a fresh session there. Confirm that CLAUDE.md contains only the local @AGENTS.md import. If Claude Code asks, approve that import only after verifying it resolves to AGENTS.md inside the generated repository. Use /context to confirm that CLAUDE.md and AGENTS.md are loaded; do not begin product work if they are not. After the required review, ask me for my idea or master prompt.

Another coding agent:

Install or upgrade Yakherd with pip, inspect the actual project folder, and run yakherd setup there. Preserve unrelated files and stop on any Yakherd-path collision. Run yakherd doctor. In the generated project, always read AGENTS.md before working and confirm it is in the active context. After installation and the required review, ask me for my idea or master prompt.

The agent can install Yakherd from PyPI, run yakherd setup, and guide you through the next step. In Codex, the generated launcher explicitly requests the five role agents; other environments use the same five role prompts as long-lived sessions. Once Yakherd is installed and its initial review passes, give the Architecture role your master prompt. Together, Yakherd plus a clear master prompt can turn an idea into usable software in Codex, Claude Code, or another capable agentic coding environment.

Yakherd improves how the work is organized and reviewed; it does not guarantee that every generated program is correct or safe. You should still review and test consequential software before relying on it.

Why Yakherd

Long-running agent projects often drift because decisions live in chat, multiple files claim authority, failed experiments remain active, and the human becomes a courier between tasks. Yakherd installs a small governance shell that makes authority, current state, decisions, evidence, and review boundaries explicit.

It is deliberately product-neutral. It does not choose your language, framework, cloud provider, database, architecture, or deployment system.

Quick Start

Install Yakherd, enter the project folder, and set it up:

python3 -m pip install --upgrade yakherd
cd ~/dev/my-project
yakherd setup

setup derives the project name from the folder, refuses to overwrite any existing Yakherd path, preserves unrelated files, and runs doctor automatically. For a different target, pass its path:

yakherd setup ~/dev/my-project

Then open the repository as the Codex project and send:

Start Yakherd

The launcher creates the Red Team agent that follows docs/prompts/bootstrap_cold_resume_review.md. Only after that review passes does Architecture preserve and extract the product master prompt. The human then confirms a bounded brief for direct Implementation or a strict planning scope; product intake is not automatically sent through Red Team.

On Windows PowerShell, the equivalent commands are:

py -m pip install --upgrade yakherd
Set-Location C:\dev\my-project
yakherd setup

Use yakherd setup --dry-run for a non-mutating preview and yakherd doctor at any time for a read-only readiness check. Low-level init and reviewed retrofit commands remain available under yakherd --help.

To run directly from source instead, clone this repository and replace yakherd in the examples with python yakherd.py.

See a Cold Resume

The strongest Yakherd claim is recoverability: a new agent should be able to open the generated repository with no implementation chat, reconstruct the project's state from its files, run the required checks, and issue an independent review.

This recording is rendered from a real isolated fresh-agent run. The session source, exact prompt and result, review, and hashes are committed beside it so the result is inspectable rather than a staged terminal animation.

What Gets Installed

• SSOT.md: authority map and conflict order.
• DECISIONS.md: durable decision owner.
• STATUS.md: bounded current-state index.
• AGENTS.md: the one authoritative set of repository operating rules.
• CLAUDE.md: a one-line Claude Code adapter that imports AGENTS.md.
• START_HERE.md: the beginner handoff and one-message Codex launch.
• Architecture, Implementation, Red Team, Temporary Branch, and Governor task prompts.
• A Codex five-role launcher, master-prompt provenance protocol, and an approval-gated GitHub project setup guide.
• docs/task_protocol.md as the generated repository's canonical owner for work modes and the independent-review circuit breaker.
• Proportional bounded/strict work modes and a two-review circuit breaker.
• Governance, review, plan, run-record, and status-history directories.
• Standard-library validators and focused tests.
• A hash-bound installation receipt.
• Windows policy Y-PROC-1: a compact installed instruction backed by yakherd exec, per-task Job Objects, one-heavy-pipeline governance, below-normal heavy-job priority, identity-bound cleanup, status, and dry-run cleanup.

See Usage and Architecture.

Existing Repositories

Retrofit mode is intentionally fail-closed. It requires a separately reviewed JSON plan with an exact allowlist and expected hashes. Do not point fresh mode at an established repository, and do not improvise a retrofit from the command line. See Retrofit Safety.

Windows Local Execution Hygiene

On Windows, run finite local work through the Y-PROC-1 broker. Heavy is the safe default; it preserves the build tool's normal internal worker count while serializing independent top-level heavy pipelines for the current user:

yakherd exec --timeout 900 -- cmake --build build
yakherd process status
yakherd process cleanup --all-owned --dry-run --verify
yakherd process resume --task TASK_ID

Use --light only for finite low-CPU work that is safe to overlap. The broker rejects known interactive, detached, watcher, daemon, and development-server forms. Y-PROC-1.1 classifies PID reuse, missing legacy evidence, and conflicting identity evidence as visible warnings, never as unrelated-work embargoes. Only a verified live Job member that failed cleanup with concrete hazard evidence is a blocker. Approved persistent-process leases remain deliberately deferred.

Existing mosaic_colmap, SPLATOMATIC, and CROCHET installations are partially mitigated. Preserve their temporary process-hygiene instructions; adopt Y-PROC-1 later through the smallest reviewed, hash-pinned retrofit rather than refreshing unrelated SSOT content.

Trust Boundary

Yakherd 1.0.0 distributed the exact package that passed the Mosaic-origin V3 independent review. Those historical audits remain provenance for the first release, not a claim that later versions have identical bytes.

For every version, RELEASE.json binds bootstrap.py and MANIFEST.json; the manifest binds every installed template. Package changes require regenerated hashes, clean acceptance evidence, and a new independent review before release. The Git tag and GitHub release then authenticate those reviewed bytes externally.

The engine remains under packages/jeff_strict_ssot_v1/ because the V1 name identifies the protocol generation. Package versions within V1 may add backward-compatible adapters only through the full acceptance and independent review cycle.

Non-Goals

The Yakherd installer does not:

• run product code or experiments (the separate, explicitly invoked yakherd exec broker runs only the command the operator supplies);
• install product dependencies;
• access project secrets;
• create automations;
• choose technical architecture;
• make Git mutations inside the target repository; or
• replace human approval for consequential decisions.

The generated GitHub guide is executed later by the coding agent only after the user verifies the authenticated account, destination, visibility, exact initial commit, remote, and first push. That guided workflow does not weaken the installer's no-network/no-Git guarantee.

Development

python3 -B -m unittest discover \
  -s packages/jeff_strict_ssot_v1/tests -v

python3 packages/jeff_strict_ssot_v1/tests/run_acceptance.py \
  --package-root packages/jeff_strict_ssot_v1 \
  --output-root .tmp/acceptance \
  --date 2026-07-20

Windows PowerShell:

python -B -m unittest discover `
  -s packages\jeff_strict_ssot_v1\tests -v

python packages\jeff_strict_ssot_v1\tests\run_acceptance.py `
  --package-root packages\jeff_strict_ssot_v1 `
  --output-root .tmp\acceptance `
  --date 2026-07-20

Read CONTRIBUTING.md before changing the audited package.

License

Apache License 2.0. See LICENSE.