# Requirements: ngn-agent

**Defined:** 2026-06-14
**Core Value:** The agent must NEVER mutate real infrastructure beyond what the limited IAM role permits, while being maximally useful for diagnostics, research, and automation.

## v1 Requirements

### Authentication & Provider

- [ ] **AUTH-01**: Agent authenticates via AWS Bedrock as primary LLM provider using boto3 SSO auth chain
- [ ] **AUTH-02**: Agent falls back to OpenRouter when Bedrock encounters errors (rate limits, 5xx, auth failures)
- [ ] **AUTH-03**: Project-local `./.aws/` config with limited SSO role mounted read-only into Docker container
- [ ] **AUTH-04**: SSO token refresh handled via AWS SDK cached registration (~7 day validity); browser login on expiry
- [ ] **AUTH-05**: OpenRouter API key stored in `~/.hermes/.env`

### Container & Security

- [ ] **CONT-01**: Hermes configured with Docker terminal backend
- [ ] **CONT-02**: Docker container runs with `--cap-drop ALL`, `--security-opt no-new-privileges`, PID limits
- [ ] **CONT-03**: `./.aws/` mounted into container as read-only volume
- [ ] **CONT-04**: AWS_PROFILE=limited environment variable set in container
- [ ] **CONT-05**: Hermes dangerous command approval enabled with manual or smart mode
- [ ] **CONT-06**: Hardline blocklist protects against catastrophic commands

### Memory & Knowledge

- [ ] **MEM-01**: Hermes persistent memory (MEMORY.md + USER.md) stores infrastructure facts
- [ ] **MEM-02**: Agent proactively saves environment facts and conventions
- [ ] **MEM-03**: Session search available for recalling past infrastructure context
- [ ] **MEM-04**: Git worktree isolation enabled for parallel branch work

### Gateway

- [ ] **GATE-01**: Telegram gateway configured and connected
- [ ] **GATE-02**: Pairing-based authorization for new users
- [ ] **GATE-03**: Scheduled daily reports and stale session cleanup

### Skills

- [ ] **SKIL-01**: Skills system operational with Hermes Skills Hub integration
- [ ] **SKIL-02**: Read-only infrastructure diagnostic skills operational
- [ ] **SKIL-03**: Jira and Confluence reporting via MCP tools

## v2 Requirements

### Enhanced

- **SKIL-04**: Self-improving auto-skills that detect and adapt to recurring patterns
- **SKIL-05**: Custom Hermes skills catalog for platform engineering workflows
- **GATE-04**: Microsoft Teams gateway

## Out of Scope

| Feature | Reason |
|---------|--------|
| Direct `~/.aws` mounting | Privileged credentials must never enter container |
| Non-AWS cloud providers | GCP/Azure deferred — focus on AWS first |
| Native mobile app | Telegram gateway covers mobile use case |
| Self-hosted model serving | Bedrock + OpenRouter sufficient |
| Kubernetes in-cluster deployment | Local agent with CLI access only |

## Traceability

| Requirement | Phase | Status |
|-------------|-------|--------|
| AUTH-01 | Phase 1 | Pending |
| AUTH-02 | Phase 1 | Pending |
| AUTH-03 | Phase 1 | Pending |
| AUTH-04 | Phase 1 | Pending |
| AUTH-05 | Phase 1 | Pending |
| CONT-01 | Phase 1 | Pending |
| CONT-02 | Phase 1 | Pending |
| CONT-03 | Phase 1 | Pending |
| CONT-04 | Phase 1 | Pending |
| CONT-05 | Phase 1 | Pending |
| CONT-06 | Phase 1 | Pending |
| MEM-01 | Phase 2 | Pending |
| MEM-02 | Phase 2 | Pending |
| MEM-03 | Phase 2 | Pending |
| MEM-04 | Phase 2 | Pending |
| GATE-01 | Phase 3 | Pending |
| GATE-02 | Phase 3 | Pending |
| GATE-03 | Phase 3 | Pending |
| GATE-04 | Phase 3 | Pending |
| SKIL-01 | Phase 4 | Pending |
| SKIL-02 | Phase 4 | Pending |
| SKIL-03 | Phase 4 | Pending |

**Coverage:**
- v1 requirements: 22 total
- Mapped to phases: 22
- Unmapped: 0 ✓

---
*Requirements defined: 2026-06-14*
*Last updated: 2026-06-14 after initial definition*