Imported from LoonanChauvette/myIO2 (AGENTS.md). Install upstream with npx skills add LoonanChauvette/myIO2. Copyright stays with the author.

AGENTS.md

myio2 is a plugin-based framework for psychoacoustic experiments — a principled restart of the myio audio engine around the plugin philosophy that powers DeepSeek Harness (the Cordis kernel): everything — device backend, engine, input, stimuli, procedures, policies, recording — is a plugin mounted into a shared context. The experiment definition is the plugin composition, which makes sessions reproducible by construction.

This file is standing orders: rules an agent needs in every session, one to three lines each, with a link to the document that owns the detail. Human contributors should read CONTRIBUTING.md; the documentation standard lives in docs/AGENTS.md; the team operating model lives in docs/team/.

Repository layout

myio/                the core: contract + infrastructure (never imports plugins)
cordis/              the vendored plugin kernel (lifecycle, services, events,
                     effects, validated config) — domain-agnostic, synced from
                     cordis-python-skeleton (see docs/architecture.md)
bundled_plugins/     DEFAULT plugins, but external: structured exactly like
                     third-party code cloned into a folder
demos/               seven end-to-end demos (real hardware by default)
tests/               pytest suite (no audio hardware needed)
docs/                this project's documentation (see docs/AGENTS.md)
scripts/             repo gates and generators (see docs/AGENTS.md)
sessions/            experiment output — git-ignored (see sessions/README.md)

The one architectural rule that matters: the render plane (audio callback) never touches the plugin machinery — the plugin system lives in the management plane (asyncio). See docs/architecture.md.

Commands

uv run pytest -q                    # the test suite (no audio hardware needed)
uv run python -m myio.doctor        # environment check
uv run python -m bundled_plugins.tools.demo_launcher --check   # headless demo sanity suite

Documentation gates (scripts/verify_*.py, CI) are listed in docs/AGENTS.md.

Working rules

• Work on a branch, never on main. Branch names are role/purpose (e.g. testing/test-engineer, docs/engineer); each role branch lives in its own worktree (see git worktree list). Merge to main only through a reviewed PR.
• One home per fact. A fact belongs to exactly one document tier; everywhere else, link to it. Never restate a rule that another document already owns — that is how documents drift. See docs/AGENTS.md.
• Every non-trivial change ships with its decision record. Rationale goes in docs/decisions/; incident stories go in docs/postmortems/; change stories go in CHANGELOG.md — never in durable prose. The how-to for all of it is CONTRIBUTING.md.
• Never commit artifacts. __pycache__/, *.pyc, *.egg-info, coverage output, and sessions/*.jsonl are git-ignored; keep it that way. Untracked session data is experiment output — archive it, don't commit it.
• Document current state, not history. No "previously", "now", "renamed" in durable prose; state what is, and link the decision that explains why.
• Claims must be true. Every API name, event, and command in the docs exists in code; every fenced Python block compiles. The gates in scripts/ enforce this on CI.