acai.sh

Open-source toolkit for spec-driven AI-assisted development built around feature.yaml specs and ACIDs (Acceptance Criteria IDs). The author's argument for why this exists and how it differs from spec-tooling neighbors lives in the specsmaxxing post.

The pitch in one line: stop asking the agent to remember what your feature is supposed to do across sessions; write a numbered list of acceptance criteria once, get the agent to reference those numbers from code and tests, and review requirements instead of files.

Components

The org ships three repos:

acai-sh/cli — TypeScript CLI distributed via npx @acai.sh/cli plus Linux/macOS GitHub releases. Apache-2.0, ~10★, created 2026-03-22.
acai-sh/server — self-hostable Elixir/Phoenix/Postgres backend that runs the dashboard, REST API, database, backup service, and reverse proxy. Apache-2.0, ~3★, created 2026-02-27.
acai-sh/docs — Mintlify-powered documentation site at acai.sh.

There's also a hosted version at app.acai.sh — author says "free for a while, or maybe forever" depending on whether usage gets expensive. The hosted/self-hosted split is conventional: code is OSS, hosting is a service.

How it fits together

feature.yaml  →  agent reads via `npx @acai.sh/cli skill`  →  agent writes code with `// AUTH-1` etc.
       │
       └────  `acai push --all` from CI  →  app.acai.sh dashboard with requirement-by-requirement review surface

The CLI's skill subcommand teaches the agent the convention — install it once per project and the agent learns to read feature.yaml, write ACID-referenced code, and emit completion/blocked states. The dashboard exists because reviewing requirements is a different shape than reviewing diffs; you want a list of "AUTH-2-1: completed, assigned to claude-code, awaiting review" not a 600-line PR.

The intended end state is a plan → implement → review loop with the LLM as the implementer and the human as the reviewer at the requirement level. CI hook examples and the loop wiring are roadmap items as of this ingest.

feature.yaml format

feature:
    name: imaginary-api-endpoint
    product: api
    description: ...

components:
    AUTH:
      name: Authn and Authz
      requirements:
        1: Accepts Authorization header with `Bearer <token>`
        1-1: Token must be non-expired, non-revoked
        2: Respects the scopes configured for the owner
        2-note: See `access-tokens.SCOPES.1` for complete list of supported scopes

constraints:
    ENG:
      requirements:
        1: All actions are idempotent
        2: All HTTP 2xx JSON responses wrap their payload in a root `data` key

The split between components (functional requirements grouped by surface area) and constraints (cross-cutting engineering invariants) is the format's main opinionation. Hierarchical numbering (2-1) gives sub-requirements an address. Sibling *-note keys carry cross-references. deprecated and replaced_by flags exist for in-spec history when stable numbering forces a rename.

How the author positions it against neighbors

From the post:

GitHub SpecKit — "vibe coding with extra steps." Different problem (more prompts, more skills) than ACID-tracked alignment.
OpenSpec — disagrees on the philosophical premise: OpenSpec says specs describe how systems currently behave; acai says specs describe how systems should behave.
Kiro — converts unstructured .md to EARS syntax. acai's feature.yaml aims for the middle between .md and EARS.
Traycer.ai — uses plain .md files; acai is more opinionated about format.

Use it like this

# in your project
npx @acai.sh/cli skill            # teach the agent the convention
# (write feature.yaml, hand the agent a prompt referencing it)

# CI / push to dashboard
ACAI_API_TOKEN=<secret> acai push --all

The agent prompt the author suggests pasting verbatim:

Dear Claude, … Start by running npx @acai.sh/cli skill. This will teach you everything you need to know about our process for spec-driven development. Then, proceed to plan and implement the features specified in our spec files.

(The "Dear Claude / Love, [your-name]" framing is the author being playful; the load-bearing instruction is the npx @acai.sh/cli skill call.)

Status — watchlist

Filed on watchlist with re-check 2026-08-03. Reasons:

Single-author org, ~13★ across all repos as of ingest, all three repos created in the last 2-3 months.
Hosted dashboard is the review surface. Self-hosting works (server is OSS) but is heavy — Elixir/Phoenix/Postgres deployment, reverse proxy included. Most users will end up on app.acai.sh, which is the author's own hosted instance with no published business model. "Free forever maybe" is fragile.
Format lock-in is real. Once the codebase has hundreds of // AUTH-2-1 references, switching from feature.yaml to a different spec tool requires a migration script.
CI/CD wiring is a roadmap item, not shipped. The end-state pitch (reactive plan→implement→review loops) depends on integrations that don't exist yet.

What would graduate it: a notable third-party project adopting the format publicly; the CI hook examples landing; a second contributor in the org; the hosted/self-hosted split clarified. The watchlist re-check should also peek at whether the author has published the "automated plan → implement → review loop" they hinted at.

Why it's worth tracking despite the watchlist filing

The ACID-as-bidirectional-reference convention has legs independently of acai.sh the product — see acceptance-criteria-ids for the portable version. Even if this specific tool fades, the pattern is likely to show up in larger systems (Cursor, Charlie Labs, GitHub) that have the distribution to make it stick.

Limitations

TypeScript CLI only; no Python or Go ports yet (probably trivial to write but currently a barrier for non-Node projects that don't want a Node dep at build time).
Server is Elixir, which is a higher self-hosting bar than the typical Go/Rust binary.
No editor integration documented — the agent learns ACIDs via the skill command, but humans authoring feature.yaml get plain YAML editing without schema validation, hover documentation, or "go to definition" on AUTH-2-1 references.
The convention is most useful for backend / functional features. UI features map awkwardly because the author explicitly excludes "design and superficial requirements" from spec scope.

specsmaxxing — the founding post, full argument and thought experiment
acceptance-criteria-ids — the convention abstracted from the tool
acai-blog — the blog at acai.sh
ceo-ai-psychosis — the post coined "AI psychosis"; acai author borrows the term self-critically
ai-assisted-workflow — Barbero's spec-before-code workflow, compatible philosophy
clean-code-coding-agents — adjacent argument about code structure as agent context
building-syntaqlite-ai — case study where lack of spec discipline produced rework
charlie-daemons, botctl, superhq, flue — adjacent stabs at the broader "reactive software factory" problem the post sketches

Repo

github.com/acai-sh — cli (10★), server (3★), docs (Mintlify) — Apache-2.0