# 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](https://github.com/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](https://github.com/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](https://github.com/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

```yaml
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 [[specsmaxxing|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

```bash
# 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 [[toolbox/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.

## Related

- [[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]], [[toolbox/superhq]], [[toolbox/flue]] — adjacent stabs at the broader "reactive software factory" problem the post sketches

## Repo

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