vexa-audio-run

Imported from CHex0K/vexa-audio-run (AGENTS.md). Install upstream with npx skills add CHex0K/vexa-audio-run. Copyright stays with the author.

AGENTS.md — the agent front door (in-repo)

Two constitutions govern everything here — read them on the docs site or in this tree:

• Architecture — the P-book (docs/docs/governance/architecture.mdx): what the software must be (P1–P23, enforced by the CI gate suite). Your change must fit these.
• Delivery — the D-book (docs/docs/governance/delivery.mdx): how change ships — the whole loop (roadmap · PREPARE · TAKE · validation · merge bar · ship bar) in one file.

This file is the actor contract: intake, claim, and how a session behaves in the checkout.

Researching Vexa? Start here

• Found something (bug, gap, docs lie)? File a GitHub issue — every report enters state: incoming and a 3-day triage SLA. Findings are contributions.
• Want to contribute? The whole roadmap comes back in one public GraphQL call:

gh api graphql -f query='
query { organization(login: "Vexa-ai") { projectV2(number: 2) {
  items(first: 100) { nodes {
    content {
      ... on Issue { number title url state milestone { title } labels(first: 10) { nodes { name } } }
      ... on DraftIssue { title body }
    }
    fieldValues(first: 20) { nodes {
      ... on ProjectV2ItemFieldSingleSelectValue {
        field { ... on ProjectV2SingleSelectField { name } } name }
    } }
  } }
} } }'

Four axes per item: Lane — the business value, named by who feels it (Google Meet · MS Teams · Zoom · API integrators · Transcription · Recordings · Webhooks & billing · First run · Production ops · Feature shelf) — match it to what your contributor actually uses. Human bar — what validation costs in human terms (Desk check · Operator run · Solo meeting · Small group · Crowd 5+ · In-the-loop UX). Setup — the infrastructure floor (None · Lite · Compose · k8s/helm). Milestone — the version it gates (currently v0.12.x).

Selection rule: filter to your contributor's lane(s), then to the Human bar and Setup they can afford. state: ready is claimable now; state: prepared after the maintainer stamp; items with no issue number are declared direction — ask about them, don't claim them.

Your issue is your PRD

A prepared issue is a worked delivery spec — read it end to end before touching code:

• Where we are (honest) — code-grounded claims (file:line), era notes where a report predates the tree. Spot-check them; a wrong claim is a finding, report it on the issue.
• Components — your waypoints: one module/seam each, with the existing harness + fixtures you compose (you don't invent scaffolding).
• Prepared solution + forks — the mechanism and the branches you may actually hit. Alternates welcome, never required.
• The acceptance table — your definition of done. Present its observations (red→green pairs, negative controls, anchors) and the PR merges — that's a promise (D10). If your bundle satisfies the table and something is still wrong, that's our table bug, not yours.
• Deployments to validate · docs surface · preferred validator — the change isn't done until its docs move with it and someone is named to witness it.

Claiming — and say hello on Discord

1. Comment on the issue to claim it (D14b).
2. Announce it on Discord — strongly recommended: one line, "taking #NNN". This opens the human-to-human channel; questions, steering, and validation scheduling all move faster once a maintainer knows a person, not just a branch.
3. Heartbeat = visible activity on the issue/PR. Hours of silence release the claim back to the queue — no hard feelings, no stuck work. Going quiet deliberately? Say so on the issue and the lease holds.

How you work the checkout

• Contribution rights are a human decision; automate the mechanics. Before the first commit, read CONTRIBUTOR_RIGHTS.md and ask the human to choose independent, employer/client-controlled, or unsure. Never choose or tick the PR declaration for them. After the human explicitly chooses the independent or corporate path, inspect repository-local user.name and user.email, surface any mismatch, and create every commit with git commit --signoff. Never change global identity, insert another person's sign-off, enable third-party remediation, or use a maintainer override. Diagnose missing/mismatched commits by SHA. Before an amend/rebase/force-push, show the exact rewrite and obtain explicit approval; prefer the DCO App's individual remediation commit on a shared branch.

• Discord is the working channel — blockers, steering, quick questions live there while you work. One rule keeps the record honest: anything decided lands back on the issue, or it didn't happen. The issue is the source of truth; Discord is the speed.

• Your own worktree BEFORE your first edit — always. A session's opening move on any work that will touch files is git worktree add ../vexa-<slug> -b <your-branch>; only then edit. You do not own main, the primary checkout, or any tree you did not create this session — even when the change "belongs on" a branch that lives there. Two tells that you are about to trespass, and the remedy for each:

  • git worktree add says the branch is "already used by worktree …" — that tree is another session's checkout, not an invitation. Branch FROM that ref into a fresh worktree of your own (git worktree add ../vexa-<slug> -b <your-branch> <their-branch>) and build on it there; coordinate the eventual merge on the issue, never in their tree.
  • git status in a tree you're about to edit shows uncommitted files you didn't write — stop, surface them, move to your own worktree. Never adopt, commit, or clean another session's uncommitted state. One worktree per session, one session per worktree — no exceptions for "just one file", docs, or governance edits (this rule was added from a session that edited another agent's checkout after seeing the first tell).

• Never fan two parallel agents onto the same hot file — write your own file, or sequence. Parallel PRs that all append to one file's tail collide on the same last line even when the additions don't interact — the v0.12.9 batch paid 5 manual conflict-resolution cycles to exactly this. The three hot files and their remedy:

  • docs/docs/changelog.mdx — do not edit it for a per-PR line. Drop a fragment at docs/changelog.d/<pr>-<slug>.md (one file per PR → zero collisions; the release collector folds them in, docs-reflects stamp intact). See docs/changelog.d/README.md. That fragment is your docs-current touch.
  • deploy/helm/tests/test_template.sh and docs/docs/deployment-kubernetes.mdx — no fragment mechanism, and not merge=union-safe (the helm test's need <count> assertions are edited when a resource count changes, not appended; the k8s page is prose). If two claimed issues both touch one of these, flag it on the issues and sequence the PRs (land one, rebase the other) rather than racing them into a conflict. This is the same "anything decided lands back on the issue" rule applied before the collision.

• Read the chart first. docs/views/architecture.dsl (~1.4k tokens) is the generated whole-graph index: every node, edge, carrier, owner. For a slice: pnpm arch:viz cluster:<domain>. If your change adds/moves a module or alters a data flow, update architecture.calm.json in the SAME change and pnpm seal:arch (P23).

• The loop — expect before you act. For every objective, write the falsifiable Expected first, act, then record the Actual (raw evidence: commands, outputs, counts — and what you did NOT check), and a Verdict. Expected ⇒ continue; unexpected ⇒ stop and interpret — an unexpected result is a finding, never something to paper over. Unfinished scaffolding you were always meant to complete is NOT "unexpected" — finish it; stop only on genuine contradiction.

• Debug ≠ deliver — the two loops. Prove a diff on the hottest loop that carries the real external semantics (live exec · overlay · spawn probe, seconds–minutes) before you package it through the release pipeline; never cut a build to find out whether the code works, never rerun a deterministic red as a "flake", and rehearse the demo path end-to-end before the human walks it. See the two loops (§7 in this tree — the law at YOUR checkout's revision; the published copy is at docs.vexa.ai/governance/delivery#the-two-loops).

• Gates green before push: node scripts/gates.mjs all (also runs on pre-push). Green is necessary, never sufficient — prove user-facing behavior at the altitude of the claim (P19): a live leg for live behavior, not just unit green.

The hard rules (from the P-book — the ones sessions trip on)

• Fix at the point of introduction, never the point of observation. A defect surfaces in a consumer but is born in a producer. Trace it hop-by-hop back to where it's introduced, then fix there. Never patch a consumer to compensate for a producer's bug — we don't work around our own bugs. Reproduce without a live meeting before you fix.
• The core owns its contracts; clients adapt. A consumer's legacy shape is translated at the client boundary, never pushed upstream into the core.
• Brick front doors are per-runtime; inject runtime dependencies. Browser-reachable front doors are types-only; node-only capability lives behind a subpath; cross-brick runtime deps are injected. The bundler is the gate a logic test passes right over.
• Source states the designed present, not its history. No "this used to be X", no bug archaeology in comments — write code as if it had always been this way.
• Report facts, then your reading — labelled as yours. State the objective, ship raw evidence (including what was NOT checked), and put "done/works" downstream of the data (P21).

Delivering — the PR

Witness your own value first. Before opening the PR, run your change live at the issue's declared human bar — your own run is the bundle's first row. You never ask another human to witness value you haven't witnessed yourself.

Then the PR carries two artifacts, judged on different axes (D8):

1. The observation bundle — your acceptance table mapped row-by-row to evidence, in the issue's own numbering, your live witness included. This answers "is the value real?"
2. The diff — which passes review and the security checks the issue names. This answers "is it correct and safe?"

A diff with no bundle is not reviewable. Authorship: agents are instruments — what you ship is yours, full responsibility, honored as full authorship and credit; no agent co-author trailers (D13).

The maintainer triages your PR by the TAKE protocol — read it to know exactly how you'll be read. Then a non-author validates the value (the attestation shape); validators are credited in release notes alongside you, and the reporter of the original bug is the preferred signer of your fix.