AkurAI-Build

public

Latest change 834088c92ff481a8a0cc0f5825c8fb9524396e7a - Build lean Git-native AkurAI CI/CD by Ólafur Búi Ólafsson

# AkurAI Build contributor guidance

## Core operating rule — mandatory

- Read `deploy.md` before every implementation, deployment, diagnosis, or operations task.
- Before running anything, check `skills/akurai-build/SKILL.md`, `./deploy.sh help`, and `./deploy.sh cli --help` for an existing supported operation.
- Use only `deploy.sh` or the `akurai` CLI for mutations. Never manually edit production files, state, services, Nginx, certificates, packages, Git history, artifacts, or databases.
- A direct shell/SSH/system command is permitted only as a bounded, read-only probe when no maintained command exists.
- After a probe succeeds, add the operation to `deploy.sh` or `akurai`, add a focused check, and update the skill and `deploy.md` before using it as an operational mutation.
- Repository source is changed only in the canonical tree, synchronized with `./deploy.sh sync`, verified by `./deploy.sh check`, and committed/pushed by `./deploy.sh publish` or `./deploy.sh release`; never patch installed/runtime copies.

## Product boundary

- AkurAI Build is a lean Git-native CI/CD controller based on Bunfork's Rust, SQLCipher, MiniJinja, bounded-HTTP, verified-artifact, and Ponytail UI foundations.
- One compiled `akurai` binary owns the CLI, API, webhooks, scheduler, build execution, artifacts, deployments, and dashboard. Do not create separate services or frontend build systems without measured need.
- Git repositories own `.akurai.yml`. Docker is the default executor; native execution is an explicit trusted-repository opt-in.
- Do not add Git hosting, issue tracking, chat, plugin marketplaces, Kubernetes operators, or speculative enterprise layers. Integrate with existing tools through Git, OCI/Docker, webhooks, CLI JSON, and HTTP.

## Canonical host and deployment

- Canonical source is `~/Projects/AkurAI-Build` on Titan. GitHub is `https://github.com/olibuijr/AkurAI-Build`.
- Production runs on Titan at `100.88.0.9:3210`. `https://akurai-builds.olibuijr.com` terminates TLS at EC2 Nginx and proxies through AkurAI-VPN.
- Use `./deploy.sh` for bootstrap, checks, builds, deployment, rollback, service status/logs, skill installation, EC2 vhost configuration, and Git publication. It forwards to Titan from other hosts.
- Do not substitute ad-hoc SSH, systemd, Docker, Nginx, package-manager, filesystem deployment, or Git publication commands. Read-only probes are allowed when diagnosing or improving `deploy.sh`; encode every repeated mutation in the script or `akurai` CLI.

## Security and data invariants

- Keep SQLCipher migrations embedded, ordered, transactional, and validated. Never edit or recreate production data manually.
- Secrets live only in protected files or the protected service environment. Never put values in source, Markdown, SQLite, logs, command arguments, or artifacts.
- Preserve constant-time API/webhook authentication, same-origin browser mutations, strict CSP, bounded bodies/connections/timeouts/logs/artifacts, immutable Git commits, and path-containment checks.
- Repository writers are privileged: pipeline commands are code. Fork builds must not receive secrets or native execution until an explicit trust model exists.
- Deployments promote the recorded artifacts of successful dependency jobs and require explicit approval when configured.

## Implementation and verification

- Keep dependencies minimal; no `unsafe`, `unwrap`, debug macros, TODOs, or unimplemented paths except the narrow reviewed SQLCipher FFI call inherited from Bunfork.
- Prefer deletion and standard platform tools. One scheduler process and SQLite are intentional until measured load requires distribution.
- Every non-trivial branch/parser/security path needs one focused runnable check.
- Run `./deploy.sh check` before publication and `./deploy.sh publish "message"` to commit/push. Never deploy a failing tree.
- Every contract change updates the closest README, example pipeline, skill, or deployment command in the same change.

## MiniJinja and Ponytail UI

- `app/pages` owns pages, `app/templates/layouts` owns inheritance, and `public` owns browser assets.
- Keep pages server-rendered with progressively enhanced plain JavaScript. No frontend framework or build step until native HTML/CSS/JS measurably fails.
- Use semantic `--pt-*` tokens, native controls, visible focus, status text plus color, 44px controls, responsive layouts, strict CSP, and no inline style/script.
- Do not add decorative gradients, glass, neon, generic indigo, terminal cosplay, nested card grids, or inaccessible custom control behavior.

## Agent operations

- Keep `skills/akurai-build/SKILL.md` synchronized with every CLI/deploy operation so BunFast and Pi agents use stable machine-readable commands.
- Agents must parse CLI JSON and verify persisted terminal states before reporting success.
- Self-healing means restart reconciliation, bounded retries, immutable history, health checks, rollback, and accumulated run evidence—not autonomous unreviewed source mutation.

## Browser automation

- Use Pi's native `agent_browser` tool for browser inspection, UI automation, and screenshots: `open` → `snapshot -i` → interact → fresh snapshot.
- Do not replace it with shell-driven browser scripts, Playwright, Puppeteer, or DevTools unless explicitly implementing browser code.

## Autonomous goal mode and pi-lens

- Use `/goal` for persistent multi-step work and call `goal_complete` only after all requirements are verified.
- Use pi-lens discovery and diagnostics while editing. Fix relevant findings and still run the project's normal checks.