# NebulaForge Agent Swarm Guidelines

This repository is designed for collaborative development by a swarm of agents and human contributors. The following guidelines help ensure safe, predictable, and high-quality evolution of the codebase.

## Architecture Overview
- Runtime: on-device inference and planning primitives (ARM/RISC-V optimized).
- Federated: secure aggregation with optional differential privacy budgets.
- Contracts: per-message data contracts (LocalProblem, SharedVariables, PlanDelta, PrivacyBudget, AuditLog).
- Governance: crypto-signed decisions and tamper-evident provenance ledger.
- Simulator: Gazebo/ROS stubs for HIL validation.
- CatOpt Bridge (EnergiBridge): optional interoperability layer for cross-domain adapters and a canonical intermediate representation.

## Tech Stack and Build
- Primary language: Python (pyproject.toml, setuptools). Packaging validated via test.sh which runs python3 -m build and pytest.
- Tests: pytest-based unit tests under tests/. Packaging and distribution checks run in test.sh.
- External dependencies: leverage existing industry-standard packages via pip when adding functionality. Ensure dependencies get added to pyproject.toml and are installed during packaging/tests.

## Testing and Validation
- Run tests with: ./test.sh
- test.sh steps: build the package (python3 -m build) and run pytest for all unit tests.
- Ensure no regressions in tests/test_*.py when implementing new features.

## Development Workflow (2–3 agents to start)
- Phase planning is driven by MVP goals: runtime core, two adapters, delta-sync scaffolding, then governance and HIL.
- Work items should be small, self-contained, and testable. Prefer minimal, correct changes.
- Before starting a new major feature, add it to this document as a new task with a clear scope.

## Contribution Rules
- Follow PEP 8 where applicable; keep modules small and focused.
- Add tests for new functionality; ensure all tests pass before proposing changes.
- Do not commit secrets (.env, credentials.json, etc.). Warn if such files exist.
- Update AGENTS.md if you introduce new major components or interfaces.
- Use non-destructive commands; avoid rewriting history or pushing to main/master without explicit permission.

## Collaboration Etiquette
- Communicate clearly about changes, blockers, and decisions.
- When starting work on a new task, mark it in this document and in any tracking tool you use (e.g., TODOs).
- If multiple agents work in parallel, align on API boundaries and data contracts to minimize merge conflicts.

## Ready-to-Publish Hint
- The repository is prepared for CI checks via test.sh. Consumers expect a robust, well-documented package. The README and packaging metadata should reflect the MVP’s practical description.

## Quick Reference Commands
- Run tests: `bash test.sh`
- List Python tests: `pytest -q tests`
- Build package: `python -m build`