Skip to content

armgit / avibe

Public Imported from GitHub
0

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.

docs(agents): reorganize project guidance (#2166)

Call White25dfe3152ffd
diff --git a/AGENTS.md b/AGENTS.md
index 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 overwrite
Avibe 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, and
never 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 an
architecture/spec-only PR; ordinary documentation and every product or test
code 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 manifest
diff --git a/docs/regression/README.md b/docs/regression/README.md
index 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.md
new file mode 100644
index 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.md
index 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`.