Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
docs(agents): reorganize project guidance (#2166)
Call White25dfe3152ffd
diff --git a/AGENTS.md b/AGENTS.mdindex f38d5ff71..ceadf47f8 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -122,39 +122,19 @@ Hard rules:explicitly with`python3 scripts/incus_regression.py delete --target worktree --slug <slug> --yes`when merged, abandoned, or stale-- `reconcile` lists every worktree environment Incus holds — including ones- created outside the runner, which no metadata-driven command can see — and- forgets metadata rows whose environment is already gone. It never deletes an- environment: no recorded field can prove one is unwanted, so that call stays- with the operator. It reports the names the daemon gave, never re-derived from- the slug, because a discovered name is bounded by what Incus accepts and- `--slug` is stricter; one it would reject gets its objects named for a manual- reclamation instead of a command that would exit on its own argument-- a metadata row is dropped only when the daemon that owns it completed a- listing whose every entry was readable, that listing held neither its project- nor its instance, and the row is not a reservation whose `up` may still be- running. A reservation lives exactly as long as its run: an `up` that fails- gives its row back while the daemon reports no project for that slug and the- row is still the one that run wrote, both read at that moment rather than- remembered from an earlier one — so a project that may bind the port, a- listing that cannot answer, and a concurrent `up` that took the slug over all- keep the row. `worktrees.json` is reached only through an accessor bound to the- daemon it describes — it reserves host ports on this machine and records what- this machine's daemon holds — so a `--remote` command cannot name it and- neither reads nor writes it: `reconcile --remote` reports the remote inventory- with no local provenance, `delete --remote` keeps the local row, and- `up --remote` requires `--host-port`+- `reconcile` reports every worktree environment held by Incus, including+ environments created outside the runner, and only forgets metadata for+ environments that are no longer present. It never deletes an environment.+- a metadata row is dropped only after a complete, readable listing shows that+ the daemon holds neither its project nor instance and the row is not a live+ `up` reservation- never use `--reset-config` / `--reset-all`, wipe regression state, or overwriteAvibe Cloud pairing / `remote_access` just to make probes pass unless asked- after any regression update, verify service health before reporting success-State and lookup notes:--- regression product state lives under `/home/avibe/.avibe`; `/home/avibe/.vibe_remote` is only the compatibility symlink-- metadata lives under the primary checkout's `.runtime/incus-regression/`, even- when the runner is invoked from a task worktree-- `.env.regression` is read from the current worktree first, then the primary checkout-- branch/master regression defaults to a locally built Show Runtime archive; packaged release installs use the packaged manifest path+The runner's reconciliation, reservation, daemon ownership, and state lookup+semantics live in `docs/regression/README.md`. Read that document when changing+the runner or diagnosing metadata cleanup.## 4. Configuration and Routing Model@@ -219,13 +199,10 @@ Source-of-truth rule:contract, require an exact-head Codex review, zero unresolved review threads,and passing CI before close-out, apply the review-loop circuit breaker, andnever merge without explicit owner instruction-- the fallback change contract names the intended behavior, affected boundaries,- and validation evidence; pause patching when one root-cause class appears on- two reviewed heads, or after three findings-bearing heads following an- architecture or data-model rewrite, then diagnose the whole class before- continuing- use the `background-watch-hook` skill for managed review and CI waits- keep one durable `--forever` combined PR/CI Watch and disable the Watch's per-cycle timeout+- the change contract names intended behavior, affected boundaries, and+ validation evidence; use the Skill's circuit breaker when findings repeat- only an explicit owner decision may make Codex findings advisory for anarchitecture/spec-only PR; ordinary documentation and every product or testcode PR retain the Skill's normal gates@@ -298,13 +275,11 @@ Source-of-truth rule:- be careful with persisted state under `~/.avibe/`, legacy `~/.vibe_remote/`, and `.runtime/incus-regression/`- do not reset or wipe regression data unless the user explicitly asks for it-## 9. Release Notes+## 9. Release Workflow-- tags follow the latest version number +1 (for example `v1.0.1` -> `v1.0.2`)-- before publishing a release, explicitly decide whether the version should notify users; put `<!-- avibe:update-notification=none -->` in the annotated tag message when update and post-update notifications should be suppressed while automatic update behavior remains enabled. The workflow emits both the current and legacy `vibe-remote` markers into the GitHub Release body for installed-client compatibility.-- for an official `v*` release, the annotated tag is the operator's only release-state input: put silent-update intent in the tag annotation, push the tag, and do not pre-create or manually edit a GitHub Release-- the official workflows stage assets and generated notes in a Draft; `Release (AI Notes)` may update notes but never publishes. The `Publish to PyPI` workflow is the single finalizer: it verifies the exact notes run, publishes the asset-complete GitHub Release, and only then allows PyPI publication so package manifests never point at private Draft assets-- GitHub-only pre-releases should use the `gh-vX.Y.ZrcN` format (for example `gh-v2.2.8rc2`) so they stay distinct from PyPI-triggering `v*` tags-- GitHub-only pre-releases must include installable artifacts in the GitHub release assets: a wheel built with `ui/dist` and bundled `vibe/show_runtime/*.tgz`, plus the sdist-- releases are published automatically by workflow after tagging/push-- Published managed-runtime manifests are availability contracts. Keep their release URLs under a scheduled manifest-verified backup/recovery guard, and publish the new assets before changing a pinned manifest so the guard never restores bytes from a different release.+- release automation is workflow-owned; do not pre-create or manually edit+ official GitHub Releases+- keep tag naming, update-notification markers, artifact requirements, and+ managed-runtime manifest safeguards in `docs/release.md`+- published managed-runtime URLs are availability contracts; publish replacement+ assets before changing a pinned manifestdiff --git a/docs/regression/README.md b/docs/regression/README.mdindex 3157fda35..0aad89ee9 100644--- a/docs/regression/README.md+++ b/docs/regression/README.md@@ -88,6 +88,11 @@ an SSH daemon or host ownership metadata.cp .env.regression.example .env.regression```+ When the runner is invoked from a task worktree, it looks for+ `.env.regression` in that current worktree first, then falls back to the+ primary checkout. Keep the worktree copy intentional because it shadows the+ primary checkout's configuration.+4. Fill in `.env.regression` with:- shared LLM credentials: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`diff --git a/docs/release.md b/docs/release.mdnew file mode 100644index 000000000..4066b5989--- /dev/null+++ b/docs/release.md@@ -0,0 +1,35 @@+# Avibe Release Workflow++This document contains the release-specific details that are too operational+for `AGENTS.md`. The workflows are the source of truth for the final commands.++## Tags and notifications++- Tags advance the latest version number, for example `v1.0.1` to `v1.0.2`.+- For an official `v*` release, the annotated tag is the only release-state+ input. Put `<!-- avibe:update-notification=none -->` in the tag annotation+ when the release should suppress update and post-update notifications while+ automatic updates remain enabled.+- Push the tag and let the official workflows create the release. Do not+ pre-create or manually edit a GitHub Release.+- The workflow emits both current and legacy `vibe-remote` update markers for+ installed-client compatibility.++## Workflow ownership and artifacts++The official workflows stage assets and generated notes in a Draft.+`Release (AI Notes)` may update notes but never publishes. `Publish to PyPI` is+the finalizer: it verifies the exact notes run, publishes the asset-complete+GitHub Release, and only then allows PyPI publication.++GitHub-only pre-releases use the `gh-vX.Y.ZrcN` format, such as+`gh-v2.2.8rc2`, so they remain distinct from PyPI-triggering `v*` tags. They+must include an installable wheel containing `ui/dist` and+`vibe/show_runtime/*.tgz`, plus the source distribution.++## Managed-runtime manifests++Published managed-runtime manifests are availability contracts. Keep their+release URLs under the scheduled manifest-verified backup/recovery guard.+Publish replacement assets before changing a pinned manifest so the guard never+restores bytes from a different release.diff --git a/standards/scenario-testing/AGENTS.md b/standards/scenario-testing/AGENTS.mdindex a7040e305..30a65f8bb 100644--- a/standards/scenario-testing/AGENTS.md+++ b/standards/scenario-testing/AGENTS.md@@ -1,105 +1,37 @@# Scenario Testing Standard-This directory is a portable standard package for capability-first, scenario-driven testing.+This directory is the portable entrypoint for capability-first,+scenario-driven testing. It adds a reusable middle layer between focused unit+tests and full end-to-end checks.-Treat this folder as the entrypoint when you are doing any of the following:+## When to use it-- designing or refactoring a project's testing architecture-- introducing scenario-harness or closed-loop flow testing-- defining reusable testing standards that should survive beyond one repository-- translating recurring manual regressions into stable automated coverage+Use this standard when designing or refactoring testing architecture,+introducing a scenario harness, defining reusable scenario metadata, or turning+recurring manual regression into automated coverage.-## Mission+Start with:-Build a testing system where feature work and bug fixes are validated as user-visible capability flows, not only as isolated unit behaviors.+- `ADOPTION.md` when adopting the standard in a new repository+- `tests/scenarios/INDEX.yaml` when working in an already-adopted project+- the target capability's `catalog.yaml`, `observations.yaml`, and scenario tests-The goal is not to replace unit tests or E2E tests.-The goal is to add a reusable middle layer that answers:+Read `STANDARD.md` for methodology and `WORKFLOW.md` for day-to-day delivery+rules. The project-specific implementation remains under the project's+`tests/scenarios/` and `tests/scenario_harness/` directories.-- what capability is being changed-- what scenarios define its success and failure boundaries-- what parts can be simulated deterministically-- what still requires contract, smoke, or manual verification+## Canonical project layout-## Operating Rules+- `tests/scenarios/INDEX.yaml` — capability index+- `tests/scenarios/<capability>/catalog.yaml` — stable scenario IDs+- `tests/scenarios/<capability>/observations.yaml` — dependency observations+- `tests/scenarios/<capability>/test_*.py` — executable scenario evidence+- `tests/scenario_harness/` — shared harness primitives-1. Start from capabilities, not files, modules, or bugs.-2. Require stable scenario IDs and reusable scenario catalogs.-3. Prefer shared harness primitives over one-off mocks.-4. Keep the harness light enough for everyday development use.-5. Turn the standard into delivery rules, not just reference docs.+Scenario work starts from user-visible capabilities, uses stable IDs, prefers+shared harness primitives, and keeps simulations deterministic. It supplements+unit and E2E tests; it does not replace either or require every real-world+check to become automated.-## Folder Map--- `README.md`- Overview and intended reuse model.-- `STANDARD.md`- The core methodology and testing pyramid.-- `ADOPTION.md`- The onboarding workflow for a testing-owner agent adopting this standard in a new project.-- `WORKFLOW.md`- The day-to-day workflow for feature work, bug fixes, reviews, and CI.-- `templates/`- Reusable templates for capability specs, scenario catalogs, dependency observations, and PR checklists.-- `examples/`- Concrete project mappings. These explain how one repo applies the standard without redefining the standard itself.--## Deterministic Navigation Rule--Assume the next agent starts from zero memory and only has this file as its prompt.--That agent must be able to find the project's scenario assets through fixed locations, not through guesswork.--Preferred project layout:--- `tests/scenarios/INDEX.yaml`- Project capability index. Read this first.-- `tests/scenarios/<capability>/catalog.yaml`- Canonical scenario IDs and coverage state for that capability.-- `tests/scenarios/<capability>/observations.yaml`- Historical dependency observations and reality-feedback notes for that capability.-- `tests/scenarios/<capability>/test_*.py`- Executable scenario evidence.-- `tests/scenario_harness/`- Shared harness primitives.--Human-facing docs may still exist elsewhere, but the project should make one location canonical for scenario metadata.--## Expected Outputs--For a project adopting this standard, the normal outputs are:--- a product and capability summary-- a capability map-- a capability spec-- a scenario catalog with stable IDs-- a harness boundary inventory-- a reusable scenario harness layer-- a dependency observation log-- project-specific reference scenarios-- PR/CI rules that enforce the standard--## Starting Rule--When adopting this standard in a new repository, start with `ADOPTION.md` before changing tests.--Use `WORKFLOW.md` only after the adoption baseline exists.--When working inside an already-adopted repository:--1. read the project's `tests/scenarios/INDEX.yaml`-2. open the target capability's `catalog.yaml`-3. open the same capability's `observations.yaml`-4. read the listed scenario test files-5. only then change production code, harness primitives, or docs--## Non-Goals--- inventing a heavy generic workflow engine up front-- forcing all real-world verification into automation-- replacing focused unit tests with giant scenario tests-- coupling the standard to Vibe Remote specifics--## Adoption Rule--When you add or modify a testing standard in this repository, update the project-specific guidance to point back to this folder rather than duplicating the standard elsewhere.+When changing this standard, update project guidance to point here instead of+copying the standard into another `AGENTS.md`.