47 lines
2.8 KiB
Markdown
47 lines
2.8 KiB
Markdown
# 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`
|