nebulaforge-offline-resilient-federated-/AGENTS.md

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