Requirements AUTH-1: Accepts Authorization: Bearer header AUTH-2: Tokens are user-scoped, providing access to any of the user's resources AUTH-3: Rejects with 401 Unauthorized
Requirements AUTH-1: Accepts Authorization: Bearer header AUTH-2: Tokens are user-scoped, providing access to any of the user's resources AUTH-3: Rejects with 401 Unauthorized
feature: name: imaginary-api-endpoint product: api description: This is an example feature spec for an imaginary REST API endpoint, using the feature.yaml format components: AUTH: name: Authn and Authz requirements: 1: Accepts Authorization header with Bearer 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: description: Constraints are for cross-cutting or under-the-hood requirements. Here are some example engineering constraints; requirements: 1: All actions are idempotent 2: All HTTP 2xx JSON responses wrap their payload in a root data key
feature: name: imaginary-api-endpoint product: api description: This is an example feature spec for an imaginary REST API endpoint, using the feature.yaml format components: AUTH: name: Authn and Authz requirements: 1: Accepts Authorization header with Bearer 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: description: Constraints are for cross-cutting or under-the-hood requirements. Here are some example engineering constraints; requirements: 1: All actions are idempotent 2: All HTTP 2xx JSON responses wrap their payload in a root data key
my-feature.ENG.2
Step 2 - Ship
Step 3 - Review
acai push
Create a free Team and Access Token at https://app.acai.sh
Expose the environment variable # .env ACAI_API_TOKEN=
.env ACAI_API_TOKEN=
.env ACAI_API_TOKEN=
Push specs and code refs to the dashboard for review acai push --all
acai push --all
acai push --all
Step 4 - Iterate / repeat
acai
plan → implement → review
Future Gazing
Thought Experiment
feature.yaml
-> From Specsmaxxing to Testmaxxing
-> From Testmaxxing to reactive software factories
Comparison to other spec-driven development tools
GitHub SpecKit
OpenSpec
Kiro
Traycer.ai
Reasons you might not like acai.sh
You might not need to write specs. If your product is low-stakes, or simple, just keep prompting.
Acai specs are opinionated. You should write 1 spec per feature (though the feature boundary or slice is up to you). My opinion is that cross-cutting feature specs are easier to iterate, and really shine when a feature touches many codebases (frontend / backend / microservice etc.) and has many implementations (Production, Staging, Fix, etc.)
ACIDs rely on stable numbering. This creates zero friction when drafting a new spec, but requires care when revising a spec: you must re-align the code whenever your spec changes (almost forgot that this is the whole point?). The feature.yaml syntax supports deprecated and replaced_by flags as well, if you want to maintain a complete spec history inline.
deprecated
replaced_by
Acai discourages you from putting design and superficial requirements in your specs. Specs are for behavior, and constraints, and nothing else. I’ve learned from experience: get it working to-spec first, then do the superficial nail polish last 💅🏼.
Acai requires you to adopt the feature.yaml format. Almost zero learning curve. I have written an introductory guide to writing them. I recommend reading that first. Use npx @acai.sh/cli skill to teach your agent how. I also wrote a spec-for-the-spec if you want to go deeper.
npx @acai.sh/cli skill
Hate it?
Requirements AUTH-1: Accepts Authorization: Bearer header AUTH-2: Tokens are user-scoped, providing access to any of the user's resources AUTH-3: Rejects with 401 Unauthorized
Requirements AUTH-1: Accepts Authorization: Bearer header AUTH-2: Tokens are user-scoped, providing access to any of the user's resources AUTH-3: Rejects with 401 Unauthorized
Perhaps these tags can help me navigate these massive PRs?
Perhaps they can point me to where, exactly, a requirement is satisfied or tested!
Perhaps I can annotate them with notes and states (todo, assigned, completed)!
Perhaps I can start tracking acceptance coverage instead of test coverage!
Can my ACIDs number and label themselves?
Is it cumbersome to keep them aligned?
How do I share specs and progress across sandboxes, branches, features and implementations?
Acai.sh - an open-source toolkit
A simple and flexible template for feature specs, called feature.yaml. Feature.yaml makes it possible to reference each requirement by ACID.
feature.yaml
Tiny CLI to power your CI and your agent (available on npm or via github release).
Webapp that serves a dashboard, and a JSON REST API (Elixir, Phoenix, Postgres).
How it works
Step 1 - Specify
feature.yaml
feature: name: imaginary-api-endpoint product: api description: This is an example feature spec for an imaginary REST API endpoint, using the feature.yaml format components: AUTH: name: Authn and Authz requirements: 1: Accepts Authorization header with Bearer 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: description: Constraints are for cross-cutting or under-the-hood requirements. Here are some example engineering constraints; requirements: 1: All actions are idempotent 2: All HTTP 2xx JSON responses wrap their payload in a root data key
feature: name: imaginary-api-endpoint product: api description: This is an example feature spec for an imaginary REST API endpoint, using the feature.yaml format components: AUTH: name: Authn and Authz requirements: 1: Accepts Authorization header with Bearer 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: description: Constraints are for cross-cutting or under-the-hood requirements. Here are some example engineering constraints; requirements: 1: All actions are idempotent 2: All HTTP 2xx JSON responses wrap their payload in a root data key
my-feature.ENG.2
Step 2 - Ship
Step 3 - Review
acai push
Create a free Team and Access Token at https://app.acai.sh
Expose the environment variable # .env ACAI_API_TOKEN=
.env ACAI_API_TOKEN=
.env ACAI_API_TOKEN=
Push specs and code refs to the dashboard for review acai push --all
acai push --all
acai push --all
Step 4 - Iterate / repeat
acai
plan → implement → review
Future Gazing
Thought Experiment
feature.yaml
-> From Specsmaxxing to Testmaxxing
-> From Testmaxxing to reactive software factories
Comparison to other spec-driven development tools
GitHub SpecKit
OpenSpec
Kiro
Traycer.ai
Reasons you might not like acai.sh
You might not need to write specs. If your product is low-stakes, or simple, just keep prompting.
Acai specs are opinionated. You should write 1 spec per feature (though the feature boundary or slice is up to you). My opinion is that cross-cutting feature specs are easier to iterate, and really shine when a feature touches many codebases (frontend / backend / microservice etc.) and has many implementations (Production, Staging, Fix, etc.)
ACIDs rely on stable numbering. This creates zero friction when drafting a new spec, but requires care when revising a spec: you must re-align the code whenever your spec changes (almost forgot that this is the whole point?). The feature.yaml syntax supports deprecated and replaced_by flags as well, if you want to maintain a complete spec history inline.
deprecated
replaced_by
Acai discourages you from putting design and superficial requirements in your specs. Specs are for behavior, and constraints, and nothing else. I’ve learned from experience: get it working to-spec first, then do the superficial nail polish last 💅🏼.
Acai requires you to adopt the feature.yaml format. Almost zero learning curve. I have written an introductory guide to writing them. I recommend reading that first. Use npx @acai.sh/cli skill to teach your agent how. I also wrote a spec-for-the-spec if you want to go deeper.