AkurAI-Build

public

Latest change b7606431f2fa7fd6d8a5bbb37716ed2fbca30651 - ops: limit controller to one worker by Ólafur Búi Ólafsson

# AkurAI Build operating contract

## Deployment workflow

1. Read `skills/akurai-build/SKILL.md` and the repository's `.akurai.yml`.
2. Run the focused local source checks.
3. Commit only the intended paths in the trusted Titan checkout and record the full commit SHA.
4. Publish the committed revision with `mcp__akurai_build_akurai_repo_sync`.
5. Confirm the hosted branch head with `mcp__akurai_build_akurai_repo_branches`.
6. Queue the exact SHA with `mcp__akurai_build_akurai_run_queue`.
7. Inspect or wait through `akurai_run_show`/`akurai_run_wait`; promote a persisted `waiting` production environment only with `akurai_run_promote`.
8. Require persisted `succeeded` state, then verify public health and the changed behavior.

## Prohibited direct mutations

Do not directly run SSH mutations, package managers, `systemctl`, Docker mutations, Nginx/certbot changes, database tools, artifact copies, raw Git push, `akurai-ec2 release`, or `deploy.sh publish|release|deploy`. Do not hand-edit anything below:

- `~/.local/lib/akurai-build`
- `~/.local/share/akurai-build`
- `~/.config/akurai-build`
- `/etc/systemd/system/akurai-build.service`
- EC2 `/etc/nginx` or `/etc/letsencrypt`

Repository source changes happen only in `~/Projects/AkurAI-Build`. A narrowly staged local commit is the only permitted Git mutation; hosted publication, CI, artifacts, approval, and deployment use the `akurai-build` MCP tools.

## Deployment

A deployable repository owns the full release contract in `.akurai.yml`:

1. `verify` runs formatting, linting, tests, and project-specific gates.
2. `package` produces an immutable artifact and recorded SHA-256.
3. An approval-gated production job consumes that artifact without rebuilding it.
4. Post-deploy acceptance verifies health and changed behavior; failure rolls back.

Agent-side flow is always:

```text
local commit → repo_sync → verify hosted head → run_queue(exact SHA) → wait/promote → persisted success → acceptance
```

Commands such as `akurai-ec2` service or edge operations may appear inside a committed pipeline job. They are not agent-side queue, publication, approval, or deployment substitutes.

AkurAI Build is self-hosted. Its current `.akurai.yml` deliberately stops after `verify` and `package`, because restarting the controller would kill the worker executing that job. A successful package run is therefore not a production deployment. Until a non-self-severing deploy stage is available through the MCP-controlled pipeline, agents must report self-host deployment as blocked rather than invoke a direct release or service command.

Every published version must match the newest `CHANGELOG.md` entry. Version components are bounded to `1..10`: patch `10` rolls to the next minor, minor `10` rolls to the next major, and `10.10.10` is terminal.

## MCP tool set

Use the configured `mcp__akurai_build_akurai_*` tools. Never invoke the installed binary's stdio protocol, direct Build HTTP, or `deploy.sh cli|mcp`. The mounted tool schema is authoritative. Current tools: `akurai_doctor`, `akurai_repo_list`, `akurai_repo_add`, `akurai_repo_host`, `akurai_repo_sync`, `akurai_repo_rename`, `akurai_repo_remove`, `akurai_repo_visibility`, `akurai_repo_branches`, `akurai_repo_tree`, `akurai_init`, `akurai_release`, `akurai_run_queue`, `akurai_runs`, `akurai_run_show`, `akurai_run_wait`, `akurai_run_logs`, `akurai_run_retry`, `akurai_run_promote`, `akurai_artifact_get`, `akurai_workers`.

Each tool returns its JSON payload as the sole `content` text entry, or `isError: true` with a message. Require persisted `succeeded` status before reporting success; `waiting` requires an explicit `akurai_run_promote`, and `queued`/`running` are incomplete. `akurai_repo_list` supports text/visibility filters; `akurai_runs` supports `repo`/`status`/`trigger` as a string, comma-separated values, or an array, plus exact `git_ref`, free-text `search`, bounded `limit`/`offset`. `AKURAI_WORKERS` configures 1–16 Titan workers (the service default is 1). Never read or expose protected token/key/secret values.

`akurai_repo_host` is the maintained migration path from an external Git remote to AkurAI Build's authenticated Smart HTTP host. It creates a bare mirror below the protected data root and updates the CI registration only after the mirror is complete. `akurai_repo_sync` is the maintained source-publication path from a trusted Titan checkout. Public Git clients use `https://akurai-build.olibuijr.com/git/NAME.git` with the protected API bearer token supplied through a credential helper; never put the token in a URL or argument.

`akurai_repo_remove` and `akurai_run_promote` are consequential — confirm intent before calling them; `akurai_repo_remove` cascades runs, jobs, logs, and artifacts.

## Learning loop

Run history, immutable commits, logs, artifact digests, deployment records, health results, tests, changelog entries, and rollback evidence are the system's knowledge. Improve commands and documentation from that evidence. Never implement autonomous unreviewed source mutation.