# Agents

This document describes the micro agents available in the MetalOS project and provides guidelines for creating and integrating agents within the Software Development Lifecycle (SDLC), incorporating industry-standard software engineering best practices.

## Software Development Lifecycle (SDLC)

Micro agents should align with the following SDLC phases:

1. **Requirements Gathering**
   - Automate verification of requirement specifications, traceability, and completeness checks.
2. **Design**
   - Generate or validate design artifacts (UML diagrams, interface contracts).
3. **Implementation**
   - Scaffold code templates, enforce style guides, run linters and formatters.
4. **Testing**
   - Execute unit, integration, and system tests; collect and report coverage metrics.
5. **Deployment**
   - Package builds, create images, and deploy to staging or production environments.
6. **Maintenance**
   - Monitor for dependency updates, security patches, and performance regressions.

## Software Engineering Best Practices

- **Version Control**: Use Git feature branches; agents should support branch checkout and tagging.
- **Code Quality**: Integrate static analysis tools (clang-tidy, flake8) and adhere to coding standards.
- **CI/CD Integration**: Automate build, test, and deployment pipelines; provide status badges and failure alerts.
- **Testing Strategy**: Encourage TDD/BDD; maintain high test coverage; isolate flaky tests.
- **Documentation**: Generate and validate README, API docs, and changelogs; ensure up-to-date references.
- **Security**: Automate vulnerability scanning (e.g., Snyk, Dependabot); enforce secret detection policies.
- **Performance Monitoring**: Collect metrics during test runs; alert on regressions.

## Directory Structure

By convention, all agent code resides under an `agents/` directory:

```
agents/
  ├── ExampleAgent/
  │     ├── main.py
  │     ├── README.md
  │     └── tests/
  └── AnotherAgent/
        └── ...
```

## Creating a New Agent

1. Create `agents/<AgentName>/`.
2. Add an entrypoint script (`main.py`, `agent.sh`) with `--help` output.
3. Include unit tests under `tests/` and CI workflow definitions.^
4. Document usage and dependencies in `agents/<AgentName>/README.md`.
5. Register the agent under **Available Agents** below.

## Available Agents

| Name         | Path                  | Description                               |
|--------------|-----------------------|-------------------------------------------|
| ExampleAgent | `agents/ExampleAgent` | Sample agent illustrating best practices. |
| BuildAgent   | `agents/BuildAgent`   | Automates the CMake build process and reports status. |
| TestAgent    | `agents/TestAgent`    | Runs project test suite and gathers results. |
| LintAgent    | `agents/LintAgent`    | Executes linters (clang-tidy, flake8) and formats code. |
| DocGenAgent  | `agents/DocGenAgent`  | Generates and validates project documentation. |
| DeployAgent  | `agents/DeployAgent`  | Packages and deploys builds to staging or production. |
| DepUpdateAgent | `agents/DepUpdateAgent` | Checks for and applies dependency updates. |
| RoadmapAgent    | `agents/RoadmapAgent`    | View or append items in docs/ROADMAP.md. |

---
*Maintain this document by updating **Available Agents**, SDLC alignment, and best practices guidelines as agents evolve.*