Acu: Instructions file for Claude Code

Acu

A framework for building LLM-driven pipelines where the filesystem defines the program. You create directories for stages, CLAUDE.md files for behavior, and quality gates for reliability. The LLM reads this structure and executes it — templates let you replicate the pattern across new domains.

Because LLMs are probabilistic, Acu treats quality gates as a first-class concern: every stage transition must pass a deterministic check before work advances. This is what makes the output reliable despite the executor being non-deterministic.

Anchor Metaphor

Acu is an office. Each pipeline is a department with its own charter (its CLAUDE.md). Each stage is a desk inside the department. Between desks there is an inspection point — a quality gate — that signs off on work before it advances. A work unit is a project moving from desk to desk through the department. The department's final deliverable is the project's report.

The Orchestrator is Operations — the only role with cross-department visibility. It routes work, reviews outputs against standards, and surfaces framework-level improvements back into how departments run. Departments stay isolated from each other; Operations is the one seam.

This is the mental model. The rest of this document — the mechanical names (pipeline, stage, gate, unit, deliverable, Orchestrator) and the structural rules — are how the office runs in practice.

Architectural Principles

Acu's architecture is organized around isolation, gates, and structure:

• Isolation — Each pipeline runs independently with its own stages, gates, and context. No pipeline can reach into another. The Orchestrator is the only component with cross-pipeline visibility.
• Two-layer gates — Every stage transition passes a deterministic structural check (file existence, word counts, section headers, cross-references) followed, where configured, by an LLM-based semantic evaluation across three tiers (stage, pipeline, system). The structural layer is binary; the semantic layer implements the Evaluator-Optimizer loop with bounded retries. Nothing advances without passing both.
• Structure as schema — Templates enforce directory layout and file requirements. CLAUDE.md files scope what context gets loaded. Validation is structural, not semantic.
• Audit trail — Every transition is logged with session ID and SHA256. syslog.sh aggregates across pipelines.
• Threat model — Pipeline isolation, input validation, and defined attack surfaces. See THREAT-MODEL.md.