Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
262 lines (189 loc) · 14.6 KB

CONTRIBUTING.md

File metadata and controls

262 lines (189 loc) · 14.6 KB
Raw

Contributing to AURA Harness

Welcome. AURA Harness is a runtime coat around agent loops — audit, policy, session export — without replacing your host. We welcome contributions from human developers, semi-autonomous assistants, and autonomous agents that follow this guide.

Agents: read Agent Contribution Workflow first. Human operators supervising agent work should use the same workflow for review.

Navigation

Section Description
Ways to contribute Pick your contribution type
Getting started Fork, branch, install
Universal expectations Standards for every PR
Ripple effects What else to update when you change X
Pull request process Issue → verify → PR
What to avoid Anti-patterns
AI agents and operators Autonomous work rules
Related documents Testing, CoC, templates

Ways to contribute

Type What you change Typical label Before coding Verify locally
Bug fix Paths named in issue bug Bug report Repro + pytest; add regression test when possible
Core framework aura/core/, aura/agents/, aura/api.py core framework Core issue pytest tests/test_core.py tests/test_core_gaps.py + related
CLI aura/cli/ cli CLI issue pytest tests/test_cli.py + manual CLI check
Membrane & pipeline aura/sequencer/, aura/hosts/, aura/membrane/, aura/observers/, exporters sequencer, hosts, membrane, observers, audit & export Membrane & pipeline pytest tests/test_v02.py tests/test_v03.py tests/test_core_gaps.py; update integration docs
Stack integration integrations/, stack-specific demos and docs integrations, examples, documentation Stack integration Mock-first; .env.example for API keys; no secrets in repo
Documentation docs/, README.md documentation Documentation issue Links valid; tone matches repo
Enhancement New behavior in scope of issue enhancement Enhancement issue Tests + CHANGELOG + ripple docs
Examples examples/ examples Issue or enhancement Script runs; update examples/README.md
Packaging / CI pyproject.toml, .github/workflows/ packaging, ci Issue Build wheel locally; CI green
Good first issue Small docs/tests/fixes good first issue Read acceptance criteria Checklist for underlying type above

Labels: .github/labels.json — synced on merge to main via sync-labels workflow.

Getting started

1. Find or open an issue

Check existing issues first.

When writing or pasting issue bodies: link other work with https://github.com/ARPAHLS/aura/issues/<N> or descriptive titles. Do not use internal planning file numbers or target release versions (v0.x) — sequencing uses phases (see ROADMAP), semver is maintainer-only via CHANGELOG.

Intent Template
Incorrect behavior Bug report
Session, spine, identity, audit Core framework
aura CLI CLI
Sequencer, Skillware host, membrane, observers Integration
Docs only Documentation
New feature Enhancement

Wait for maintainer feedback on large or breaking work before investing in a big PR.

2. Fork and clone

git clone https://github.com/<your-username>/aura.git
cd aura
git remote add upstream https://github.com/ARPAHLS/aura.git

3. Sync and branch

git fetch upstream
git checkout main
git pull upstream main
git checkout -b fix/issue-<number>-short-description

4. Install

Requires Python 3.10+.

py -3.13 -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate     # macOS/Linux
pip install -e ".[dev]"

Skillware host work:

pip install -e ".[dev,skillware]"

See docs/TESTING.md for lint and CI parity.

5. Implement and verify

Follow Ripple effects, then Pull request process.

Universal expectations

Code of conduct

Follow the Code of Conduct. We welcome autonomous logical systems that adhere to repo standards; operators remain accountable for merged work.

Style

  • No emojis in source, docs, commits, or PR titles.
  • Black (black aura tests integrations examples) and Flake8 (flake8 aura tests integrations examples) — see TESTING.md.
  • Typed Python where the surrounding code uses types; match existing naming and structure.

Scope

  • Change only what the issue requires.
  • Do not bump pyproject.toml version or CITATION.cff unless a maintainer or release issue explicitly asks.
  • Do not commit AURA_PLAN.md (local, gitignored) or secrets (.env, keys, tokens). Use .env.example for documented placeholders.

Tests and CI

  • Behavior changes require tests in tests/.

  • Run before opening a PR:

    pytest
black aura tests integrations examples
flake8 aura tests

  • Shared fixtures: tests/conftest.py (aura_home, run_aura for CLI subprocess tests).

  • Full suite is 200+ tests across core, CLI, examples smoke, spectrum, capabilities, host stress sim, and coat flow report — see TESTING.md.

  • CI runs on PRs via .github/workflows/ci.yml (Python 3.10–3.13 matrix; gate job lint-test: pytest with coverage report, black, flake8). Steps are defined once in .github/workflows/reusable-test.yml. Each matrix cell also runs pip-audit as a warn-only dependency check; its findings or audit errors do not fail the gate or block a PR. See TESTING.md for the exact commands.

  • Wait for green checks before requesting review.

CHANGELOG

When a PR changes user-visible behavior (SDK, CLI, export shape, default session behavior, new commands):

  • Add entries under [Unreleased] in CHANGELOG.md (Keep a Changelog sections: Added / Changed / Fixed / Removed).
  • Do not add version headers or cut releases — maintainers tag releases.

Pure internal refactors with no user-visible effect may omit CHANGELOG; ask on the issue if unsure.

Ripple effects (if you change X, update Y)

If you change… Also update…
Public SDK (aura/api.py, SessionRun methods) docs/getting-started.md, docs/using-aura.md, docs/concepts.md, tests, CHANGELOG
Session / spine event shape spec/aura-event.schema.json (if applicable), docs/outputs.md, tests, CHANGELOG
Agent profile / registry fields docs/trust-paths.md, docs/aura-levels.md, docs/using-aura.md, aura/agents/profile.py persistence, tests, CHANGELOG
capabilities[] / SecretBroker aura/core/capabilities.py, aura/core/secrets.py, aura/core/payload_redaction.py, aura/membrane/egress.py, docs/capabilities.md, docs/using-aura.md, docs/outputs.md, docs/skillware-integration.md, integrations/openai/README.md, examples/14-capability-broker/, tests/test_capability_broker.py, capability + host stress sims, CHANGELOG
spectrum.level / enforcement rules aura/core/spectrum_enforcement.py, docs/aura-levels.md, docs/comparison.md, docs/ROADMAP.md, tests/test_spectrum_enforcement.py, stress sim / flow report scripts, CHANGELOG
spectrum.services[] / field-service wiring aura/core/spectrum_services.py, aura/observers/presets/limit.py, spec/manifest.schema.json, docs/observers.md, docs/field-services.md, docs/using-aura.md, tests/test_spectrum_services.py, stress sim / flow report scripts, CHANGELOG
escalations[] playbooks aura/core/escalations.py, aura/core/constraints.py (escalation_pause), aura/agents/profile.py, docs/observers.md, docs/outputs.md, examples/12-escalation-playbooks/, tests/test_escalations.py, tests/test_example_12_escalation_playbooks.py, stress sim, CHANGELOG
Constraint rule types docs/concepts.md, docs/capabilities.md (for capability_scope), docs/aura-levels.md (for schema_check), aura/core/constraints.py, aura/core/schema_validation.py, tests/test_schema_checks.py, stress sim, CHANGELOG
Sequencer step model spec/sequencer.schema.json, docs/sequencer.md, tests/test_v02.py, CHANGELOG
Skillware host / egress integrations/skillware/ (when shipped), docs/skillware-integration.md redirect, CHANGELOG
Integration example (Ollama, API, framework) integrations/<stack>/, docs/integrations/README.md, .env.example, CHANGELOG
CLI commands or flags docs/getting-started.md, README.md quick start line, docs/outputs.md (export/compare shapes), CHANGELOG
New core example Numbered folder examples/NN-short-name/ with main.py + README.md, examples/README.md, onboarding learning path if applicable
Architecture terminology docs/architecture.md, docs/INDEX.md, README.md diagrams (keep in sync)
Public docs tree / INDEX tiers docs/INDEX.md, cross-links from getting-started.md, onboarding.md, ROADMAP.md
Release / PyPI behavior docs/PUBLISHING.md, .github/workflows/publish-pypi.yml, CHANGELOG
PR CI workflow .github/workflows/ci.yml, .github/workflows/reusable-test.yml, docs/TESTING.md, CONTRIBUTING.md
Issue template fields .github/labels.json if new label needed; run label sync
Version (maintainer only) pyproject.toml, aura/__init__.py, CITATION.cff, CHANGELOG release section, Zenodo if archived

When in doubt, search the repo for the symbol or term you changed and update docs that reference it.

Pull request process

  1. Link an issue — Fixes #123 or Refs #123 in the PR description.
  2. Branch — feature branch on your fork, not direct commits to upstream main.
  3. Implement — follow Ways to contribute and Ripple effects.
  4. Verify locally — pytest --ignore=tests/integration, black aura tests integrations examples, flake8 aura tests integrations examples.
  5. CHANGELOG — [Unreleased] entry when user-visible.
  6. PR template — complete pull request template honestly.
  7. Push — open PR to ARPAHLS/aura main.
  8. CI — fix failures; address review on the same branch.

Commit messages

  • Imperative mood: Add audit report findings for denied tools
  • No emojis; no AI Co-authored-by: trailers
  • Reference issue when helpful: Fix session export agent_ref (#42)

What to avoid

  • Bypassing the membrane — do not document or test “call Skillware directly” as the blessed path unless the issue is explicitly about fallback/offline mode.
  • God modules — keep changes focused; no unrelated refactors.
  • Orchestrator creep — AURA wraps loops; do not add model routing or tool frameworks into core.
  • Deleting vision — do not remove ROADMAP/narrative content without maintainer agreement.
  • Placeholder docs — no “TODO: document” in user-facing paths you touch.
  • Unrequested version bumps — see Maintainer: cutting a release.
  • Hardcoded vendors — use adapters and host patterns; no “only OpenAI” assumptions in core.

AI agents and operators

Autonomous and semi-autonomous agents are welcome when they:

  • Follow Agent Contribution Workflow
  • Link issues and stay in scope
  • Run tests and linters before requesting review
  • Update ripple docs and CHANGELOG when required
  • Do not commit secrets or gitignored local plans

Operators must review agent output, run verification, and own the PR. Agents should not merge their own PRs unless explicitly delegated by maintainers.

Architecture principles (do not violate in core)

  • Events before features — meaningful actions emit to the audit spine.
  • Wrap, don't replace — the user's loop stays in their host.
  • Layered identity — agent_ref for humans/CI, ULID internal id, external ids in trailer.
  • Observers don't enforce — policy lives in constraints + egress; observers subscribe only.

Related documents

Document Purpose
Agent Contribution Workflow Agents and supervising operators
TESTING.md pytest, black, flake8, pre-PR checklist
Code of Conduct Humans and autonomous logical systems
SECURITY.md Vulnerability reporting
PUBLISHING.md PyPI and release tags
ROADMAP.md Shipped vs deferred (do not re-delete vision)
Issue templates Bug, docs, core, CLI, enhancement, membrane & pipeline, stack integration
.github/labels.json Label definitions
CHANGELOG.md User-facing history
CITATION.cff Software citation metadata

Maintainer: cutting a release

Contributor PRs must not bump version unless asked. Maintainers cut releases:

Touch Every release?
pyproject.toml → version Yes
aura/__init__.py → __version__ Yes
CHANGELOG.md Yes — move [Unreleased] to ## [X.Y.Z] - date
CITATION.cff → version, date-released Yes
Git tag vX.Y.Z + GitHub Release Yes — triggers PyPI publish
README.md install pin examples Optional

Thank you for helping make agent runs auditable, policy-bound, and portable.